infiniband-diags ReStructured Text documentation
================================================
Having documentation in ReStructured Text has the following benefits
1) The addition of common functionality (options, config files, etc.) can be
documented once and then included in documents for multiple tools.
1a) Documentation source is more straight forward and writers can
concentrate on the features which are unique to each tool.
2) Documentation can be generated into multiple formats (man, html) not just
man pages.
3) Documentation for any individual tool is complete within that page. (There
is no referencing of other documents and guessing which "common" options
apply.)
Instructions
------------
Place main ``rst`` files in the rst directory. ``common include`` rst files
should be in rst/common.
"git add" should _only_ be run on the rst source files themselves.
The best way to update generated documentation after changes is to [re]run
configure. autoconf will run the ``generate`` script if rst2man is available
on your system. If rst2man is not available, tarball and source rpm
distributions contain the doc/man/\*.in files and can be built from those files
a users system without rst2man. Of course they will not get any changes made
to the rst files. Therefore developers are required to have rst2man[*] installed.
[*] rst2man is available in the python-docutils package.
Common files
------------
Common documents should be placed in the rst/common directory. Common files should not be put
in the 'main' rst directory. The automated conversion script will try and
make documents out of them.
There are 2 types of common files
1) common options
The common options are text which describes a common option.
The naming conventions is:
opt_<option>.rst
2) common sections
A common section contains a section header and documents a more
advanced feature such as a config file. The naming convention
for the common section is:
sec_<section>.rst.
Common documents should actually document features which are intended to be
common across multiple tools. Within the code these features are contained in
ibdiag_common or a sub library such as ibnetdisc or an external library such as
the node name map feature.
Examples
--------
The "man" page text is:
::
<text>
.. include:: common/opt_L.rst
<text>
.. include:: common/sec_config-file.rst
The common option "L" is:
::
.. Define the common option -L
**-L** The address specified is a LID
And the common Section is:
::
.. Common text for the config file
CONFIG FILE
-----------
@IBDIAG_CONFIG_PATH@/ibdiag.conf
A global config file is provided to set some of the common options for all
tools. See supplied config file for details.