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.