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.