From 02478769f66388228ac241599d8b735830ad3e5f Mon Sep 17 00:00:00 2001 From: Charles Stephens Date: Wed, 25 Feb 2026 19:59:49 +0000 Subject: [PATCH] Updated documentation #604 Updated configuration documentation to make it more explicit that clush.conf is in ConfigParser format and in the RST docs clarified that the default run-time global section as `[Main]`. Updated references to ReadTheDocs to use both https and the current externally facing hostname. Regenerated manpages from text sources. Closes #604 --- README.md | 4 ++-- conf/groups.conf | 2 +- doc/man/man1/clubak.1 | 6 +++--- doc/man/man1/cluset.1 | 6 +++--- doc/man/man1/clush.1 | 6 +++--- doc/man/man1/nodeset.1 | 6 +++--- doc/man/man5/clush.conf.5 | 11 +++++++++-- doc/man/man5/groups.conf.5 | 4 ++-- doc/sphinx/config.rst | 11 +++++++++++ doc/sphinx/release.rst | 2 +- doc/txt/clubak.txt | 2 +- doc/txt/cluset.txt | 2 +- doc/txt/clush.conf.txt | 11 ++++++++++- doc/txt/clush.txt | 2 +- doc/txt/groups.conf.txt | 2 +- doc/txt/nodeset.txt | 2 +- lib/ClusterShell/__init__.py | 2 +- 17 files changed, 54 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 7351fe65..2e7a87e9 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ Documentation Online documentation is available here: - http://clustershell.readthedocs.org/ + https://clustershell.readthedocs.io/ The Sphinx documentation source is available under the doc/sphinx directory. Type 'make' to see all available formats (you need Sphinx installed and @@ -90,7 +90,7 @@ Web site: Online documentation: - http://clustershell.readthedocs.org/ + https://clustershell.readthedocs.io/ Github source repository: diff --git a/conf/groups.conf b/conf/groups.conf index 092a0e0b..f026ae6f 100644 --- a/conf/groups.conf +++ b/conf/groups.conf @@ -1,7 +1,7 @@ # ClusterShell node groups main configuration file # # Please see `man 5 groups.conf` and -# http://clustershell.readthedocs.org/en/latest/config.html#node-groups +# https://clustershell.readthedocs.io/en/latest/config.html#node-groups # for further details. # # NOTE: This is a simple group configuration example file, not a diff --git a/doc/man/man1/clubak.1 b/doc/man/man1/clubak.1 index 35f2aa9e..bc02824b 100644 --- a/doc/man/man1/clubak.1 +++ b/doc/man/man1/clubak.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CLUBAK" "1" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.TH "CLUBAK" 1 "2025-01-23" "1.9.3" "ClusterShell User Manual" .SH NAME clubak \- format output from clush/pdsh-like output and more .SH SYNOPSIS @@ -133,12 +133,12 @@ node2: 9 .sp \fBcluset\fP(1), \fBclush\fP(1), \fBnodeset\fP(1), \fBgroups.conf\fP(5). .sp - +\fI\%https://clustershell.readthedocs.io/\fP .SH BUG REPORTS .INDENT 0.0 .TP .B Use the following URL to submit a bug report or feedback: - +\fI\%https://github.com/cea\-hpc/clustershell/issues\fP .UNINDENT .SH AUTHOR Stephane Thiell diff --git a/doc/man/man1/cluset.1 b/doc/man/man1/cluset.1 index 2a07b346..b7c97b02 100644 --- a/doc/man/man1/cluset.1 +++ b/doc/man/man1/cluset.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CLUSET" "1" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.TH "CLUSET" 1 "2025-01-23" "1.9.3" "ClusterShell User Manual" .SH NAME cluset \- compute advanced cluster node set operations .SH SYNOPSIS @@ -477,12 +477,12 @@ command and also to conform with ClusterShell\(aqs \(dqclu*\(dq command nomencla .sp \fBclubak\fP(1), \fBclush\fP(1), \fBnodeset\fP(1), \fBgroups.conf\fP(5). .sp - +\fI\%https://clustershell.readthedocs.io/\fP .SH BUG REPORTS .INDENT 0.0 .TP .B Use the following URL to submit a bug report or feedback: - +\fI\%https://github.com/cea\-hpc/clustershell/issues\fP .UNINDENT .SH AUTHOR Stephane Thiell diff --git a/doc/man/man1/clush.1 b/doc/man/man1/clush.1 index a9d6c737..2f5be8f2 100644 --- a/doc/man/man1/clush.1 +++ b/doc/man/man1/clush.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CLUSH" "1" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.TH "CLUSH" 1 "2025-01-23" "1.9.3" "ClusterShell User Manual" .SH NAME clush \- execute shell commands on a cluster .SH SYNOPSIS @@ -408,12 +408,12 @@ File in which interactive \fBclush\fP command history is saved. .sp \fBclubak\fP(1), \fBcluset\fP(1), \fBnodeset\fP(1), \fBreadline\fP(3), \fBclush.conf\fP(5), \fBgroups.conf\fP(5). .sp - +\fI\%https://clustershell.readthedocs.io/\fP .SH BUG REPORTS .INDENT 0.0 .TP .B Use the following URL to submit a bug report or feedback: - +\fI\%https://github.com/cea\-hpc/clustershell/issues\fP .UNINDENT .SH AUTHOR Stephane Thiell diff --git a/doc/man/man1/nodeset.1 b/doc/man/man1/nodeset.1 index 6133528e..e20e2a11 100644 --- a/doc/man/man1/nodeset.1 +++ b/doc/man/man1/nodeset.1 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "NODESET" "1" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.TH "NODESET" 1 "2025-01-23" "1.9.3" "ClusterShell User Manual" .SH NAME nodeset \- compute advanced nodeset operations .SH SYNOPSIS @@ -501,12 +501,12 @@ command and also to conform with ClusterShell\(aqs \(dqclu*\(dq command nomencla .sp \fBclubak\fP(1), \fBcluset\fP(1), \fBclush\fP(1), \fBgroups.conf\fP(5). .sp - +\fI\%https://clustershell.readthedocs.io/\fP .SH BUG REPORTS .INDENT 0.0 .TP .B Use the following URL to submit a bug report or feedback: - +\fI\%https://github.com/cea\-hpc/clustershell/issues\fP .UNINDENT .SH AUTHOR Stephane Thiell diff --git a/doc/man/man5/clush.conf.5 b/doc/man/man5/clush.conf.5 index d2bab5c8..b10e3ed9 100644 --- a/doc/man/man5/clush.conf.5 +++ b/doc/man/man5/clush.conf.5 @@ -27,11 +27,14 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "CLUSH.CONF" "5" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.TH "CLUSH.CONF" 5 "2025-01-23" "1.9.3" "ClusterShell User Manual" .SH NAME clush.conf \- Configuration file for clush .SH DESCRIPTION .sp +\fBclush\fP(1) configuration files are in Python\(aqs ConfigParser format. +.SS Locations +.sp \fBclush\fP(1) obtains configuration options from the following sources in the following order: .INDENT 0.0 @@ -221,7 +224,11 @@ from \fIclush.conf\fP\&. External commands whose outputs were used by \fBclush\ .sp \fBclush\fP(1), \fBgroups.conf\fP(5), \fBsshpass\fP(1), \fBsudo\fP(8). .sp - +\fI\%https://clustershell.readthedocs.io/\fP +.sp +Python ConfigParser +.sp +\fI\%https://docs.python.org/3/library/configparser.html\fP .SH AUTHOR Stephane Thiell, .SH COPYRIGHT diff --git a/doc/man/man5/groups.conf.5 b/doc/man/man5/groups.conf.5 index d252b651..c470021e 100644 --- a/doc/man/man5/groups.conf.5 +++ b/doc/man/man5/groups.conf.5 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "GROUPS.CONF" "5" "2025-01-23" "1.9.3" "ClusterShell User Manual" +.TH "GROUPS.CONF" 5 "2025-01-23" "1.9.3" "ClusterShell User Manual" .SH NAME groups.conf \- Configuration file for ClusterShell node groups .SH DESCRIPTION @@ -206,7 +206,7 @@ Local groups.conf user configuration file (default installation for pip \-\-user .sp \fBclubak\fP(1), \fBcluset\fP(1), \fBclush\fP(1), \fBnodeset\fP(1) .sp - +\fI\%https://clustershell.readthedocs.io/\fP .SH AUTHOR Stephane Thiell, .SH COPYRIGHT diff --git a/doc/sphinx/config.rst b/doc/sphinx/config.rst index 6a626d0e..e349e916 100644 --- a/doc/sphinx/config.rst +++ b/doc/sphinx/config.rst @@ -11,6 +11,11 @@ clush clush.conf ^^^^^^^^^^ +The *clush.conf* files are parsed with Python's `ConfigParser`_ + +Locations +""""""""" + The following configuration file defines system-wide default values for several ``clush`` tool parameters:: @@ -34,6 +39,12 @@ will be tried first for ``clush``:: $CLUSTERSHELL_CFGDIR/clush.conf +Settings +"""""""" + +Settings that apply to all ``clush`` :ref:`run modes ` are +contained within the ``[Main]`` section. + The following table describes available ``clush`` config file settings. +-----------------+----------------------------------------------------+ diff --git a/doc/sphinx/release.rst b/doc/sphinx/release.rst index 9fcd6c8a..7780d520 100644 --- a/doc/sphinx/release.rst +++ b/doc/sphinx/release.rst @@ -559,7 +559,7 @@ Main changes in 1.7 ^^^^^^^^^^^^^^^^^^^ This new version comes with a refreshed documentation, based on the Sphinx -documentation generator, available on http://clustershell.readthedocs.org. +documentation generator, available on https://clustershell.readthedocs.io. The main new features of version 1.7 are described below. diff --git a/doc/txt/clubak.txt b/doc/txt/clubak.txt index 1349f36b..084c033b 100644 --- a/doc/txt/clubak.txt +++ b/doc/txt/clubak.txt @@ -88,7 +88,7 @@ SEE ALSO ``cluset``\(1), ``clush``\(1), ``nodeset``\(1), ``groups.conf``\(5). -http://clustershell.readthedocs.org/ +https://clustershell.readthedocs.io/ BUG REPORTS =========== diff --git a/doc/txt/cluset.txt b/doc/txt/cluset.txt index 06482009..8d365e11 100644 --- a/doc/txt/cluset.txt +++ b/doc/txt/cluset.txt @@ -278,7 +278,7 @@ SEE ALSO ``clubak``\(1), ``clush``\(1), ``nodeset``\(1), ``groups.conf``\(5). -http://clustershell.readthedocs.org/ +https://clustershell.readthedocs.io/ BUG REPORTS =========== diff --git a/doc/txt/clush.conf.txt b/doc/txt/clush.conf.txt index d35eb468..bcb80813 100644 --- a/doc/txt/clush.conf.txt +++ b/doc/txt/clush.conf.txt @@ -17,6 +17,11 @@ Configuration file for `clush` DESCRIPTION =========== +``clush``\(1) configuration files are in Python's ConfigParser format. + +Locations +--------- + ``clush``\(1) obtains configuration options from the following sources in the following order: @@ -186,4 +191,8 @@ SEE ALSO ``clush``\(1), ``groups.conf``\(5), ``sshpass``\(1\), ``sudo``\(8\). -http://clustershell.readthedocs.org/ +https://clustershell.readthedocs.io/ + +Python ConfigParser + +https://docs.python.org/3/library/configparser.html diff --git a/doc/txt/clush.txt b/doc/txt/clush.txt index 317f3704..9c1e3566 100644 --- a/doc/txt/clush.txt +++ b/doc/txt/clush.txt @@ -307,7 +307,7 @@ SEE ALSO ``clubak``\(1), ``cluset``\(1), ``nodeset``\(1), ``readline``\(3), ``clush.conf``\(5), ``groups.conf``\(5). -http://clustershell.readthedocs.org/ +https://clustershell.readthedocs.io/ BUG REPORTS =========== diff --git a/doc/txt/groups.conf.txt b/doc/txt/groups.conf.txt index 0012cb30..4ca70b76 100644 --- a/doc/txt/groups.conf.txt +++ b/doc/txt/groups.conf.txt @@ -184,4 +184,4 @@ SEE ALSO ``clubak``\(1), ``cluset``\(1), ``clush``\(1), ``nodeset``\(1) -http://clustershell.readthedocs.org/ +https://clustershell.readthedocs.io/ diff --git a/doc/txt/nodeset.txt b/doc/txt/nodeset.txt index 3a6f6aac..ac5324da 100644 --- a/doc/txt/nodeset.txt +++ b/doc/txt/nodeset.txt @@ -290,7 +290,7 @@ SEE ALSO ``clubak``\(1), ``cluset``\(1), ``clush``\(1), ``groups.conf``\(5). -http://clustershell.readthedocs.org/ +https://clustershell.readthedocs.io/ BUG REPORTS =========== diff --git a/lib/ClusterShell/__init__.py b/lib/ClusterShell/__init__.py index 6a559a18..01627d0b 100644 --- a/lib/ClusterShell/__init__.py +++ b/lib/ClusterShell/__init__.py @@ -38,4 +38,4 @@ __version_info__ = tuple([ int(_n) for _n in __version__.split('.')]) __date__ = '2025/01/23' __author__ = 'Stephane Thiell ' -__url__ = 'http://clustershell.readthedocs.org/' +__url__ = 'https://clustershell.readthedocs.io/'