Command Docs

The mechanics in Sphinx for command (and FISH) documentation is an extension built by Itasca. It is heavily reliant on expectations of well-formed markup. Properly-formed documentation also rests on a fairly large set of grammatical and stylistic conventions. This document will attempt to cover both at the same time by anatomizing a command doc to show what is happening. First, a complete file:

.. block zone fluid command

:lcmd:`block zone fluid` command
################################

.. rubric:: Syntax
   :class: h2

.. command:: Block.zone.Fluid keyword <range>
   :module: blockzone
   :kwlist:

   Assign fluid properties to zones.

   .. kwd:: Property keyword ...

      .. kwd:: Bulk-Modulus :flt:`f`

         Set the bulk modulus of the fluid in the matrix.

      .. kwd:: Permeability :flt:`f`

         Set the fluid flow mobility coefficient in the matrix zones (SI units of m\ :sup:`2`/(Pa/s)).

      .. kwd:: Porosity :flt:`f`

         Set the porosity for fluid flow in the matrix zones.

.. Usage Example
   +++++++++++++

   The following example illustrates how :cmd:`block.zone.fluid` can be used

   .. seealso::

And now, breaking it down:

.. block zone fluid command

The start of a command cannot be the title. Put a comment, or a link anchor, or something on line 1. Note on the why of this below.[1] Here and anywhere between items in an rst file, which is always white-space aware, put two carriage returns.

:lcmd:`block zone fluid` command
################################

Document title. Use of :lcmd: role causes the command to be presented in code-font text. As noted elsewhere, please always use the character “#” for title underlining and be sure it extends at least as long as the line above it.

.. rubric:: Syntax
   :class: h2

The title is always followed with this, uniformly. This puts the heading “Syntax” in second-level heading formatting (that comes from :class: h2) on the page without also putting it on the navigation tree. Review ICG: Sections for explanation.

.. command:: Block.zone.Fluid keyword <range>
   :module: blockzone
   :kwlist:

The .. command:: directive. This is pure Itasca.[2] Its parts are as follows.

  • the command words are written with dots where spaces occur in the string literal for the command. Capital letters are used to indicate which characters are needed to be present, minimally, for correct identification of the command by the command parser. In output, these characters will be underlined. This capitalization effect is specific to the .. command:: and .. kwd:: directives; it would not work, for instance, in the doc title.
  • the :module: option is required. All commands of like type should carry an identical string here (there are 12 block zone commands, for instance, and all of them say :module: blockzone here). This “tagging” of the commands is used to build the tables of commands that appear elsewhere.
  • the :kwdlist: option causes a box containing the first-level keywords of the command to be listed below the command signature. The keywords within the box are links that will go to the keyword as described lower on the page. In bigger commands, this is way useful and cool. The box is not created if this is omitted. Commands that have no major keywords should omit this (though if there are no keywords at all, it won’t do anything anyway if included). Commands with more than five keywords should include it. If there are one to four keywords, use your judgment; likely it can be omitted as being more trouble than it is worth.

Observe indentations!!: In this example, everything between .. command:: and .. Usage Example constitutes the content of the .. command:: directive and must religiously and coherently maintain indentation level consistency (more to follow).

Assign fluid properties to zones.

This is the description of the command in general. It must follow indentation level properly. It is brief in this example, but in general it may be multiple paragraphs if needed (though this is not encouraged). Also, these two conventions are really important.

  • Make the first line as brief as possible. All words up to the first period will be used as the command description as offered on the command table(s) where it appears.
  • Always always always use imperative mood for command description, particularly this first line, and not indicative mood (“Assign fluid properties…”, not “Assigns fluid properties…”). Only the former usage yields complete sentences.
.. kwd:: Property keyword ...

   .. kwd:: Bulk-Modulus :flt:`f`

      Set the bulk modulus of the fluid in the matrix.

   .. kwd:: Permeability :flt:`f`

      Set the fluid flow mobility coefficient in the matrix zones (SI units of m\ :sup:`2`/(Pa/s)).

   .. kwd:: Porosity :flt:`f`

      Set the porosity for fluid flow in the matrix zones.

Looking at this bit altogether, what you see is that this command has only one first-level keyword (property), which itself takes one of three keywords. Since there isn’t much to say about the property keyword, no verbiage appears beneath it at the “k” indentation level, as is seen, by contrast, in any of the three child keywords.

The capitalization technique seen with the .. command:: directive is in effect for the .. kwd:: directive.

As with the command, the keywords can take short or long descriptive text beneath them, as long as it maintains indentation level properly.

Keyword level is handled solely by indentation level, thus a keyword at any level is just formed with .. kwd:: (no need for .. kwd1::, .. kwd2::, etc.).

There is no limit to keyword indentation levels, though use of many levels probably indicates a poorly formed command.

File Names and Filing

By convention, all command files are named with the prefix “cmd_” in front, followed by the words that make up the command (literally), with dots separating words where a space appears in the command. Thus the command block.face.apply-remove should be found in a file named “cmd_block.face.apply-remove.rst”.

Where is this file? It should be found in a “../doc/manual” folder + (likely) subfolder(s) somewhere near the source code that builds the command. So the above example is found at “..3dec/block/doc/manual/block_manual/block_commands/block.face/cmd_block.face.apply-remove.rst”.

_

[1]This is a buggy outcome of the combination of ICG customization and Sphinx 1.6 (1.4 didn’t do this). The ICG bit: the doc set uses the custom directives .. commandindex:: and .. fishindex:: to gather up commands and FISH docs and put them on the navigation tree. However, in Sphinx 1.6 this customization is fooled when the very first thing in the doc is role markup (e.g., :lcmd:`zone.create`). When this happens, the doc is created and the title appears as it should, and the command will appear on the command index table that is built using the directive, but the doc does not appear on the tree. This will happen with any role markup (e.g., :math: or :emphasis: would do it too). Since all commands/FISH should start with :lcmd:/:lfish:, this is a problem that we are solving for the moment with the “put a comment/link target at the top” workaround.
[2]ICG customizations are principally defined in the document “fishdomain.py” that is found in “common/utility/extensions”.