Command Docs

Verified representative command doc: \3dec\block\doc\manual\block_manual\block_commands\block.face\cmd_block.face.triangulate.rst
View Page: block face triangulate

Command docs heavily rely on the Itasca-written extension to Sphinx contained in the file fish_domain.py.

The customizations require proper markup. Errors, or worse, exceptions may occur when markup is mangled, so this is important.

The line-by-line walkthrough below explains the parts of a command doc (using the file named above) and points out which parts are ICG customizations. This is the file in its entirety.

Important

All command document file names start with cmd_, end with .rst, and use the command words (with dots) in the middle.

cmd_block.face.triangulate.rst

``block face triangulate`` command
######################################

.. rubric:: Syntax
   :class: h2

.. command:: Block.face.Triangulate <keyword> <range>
   :module: blockface
   :kwlist:

   Triangulate faces of rigid blocks to increase the number of vertices on a face.  If no keyword is supplied, the minimum number of triangles are created.

   .. kwd:: Edge-Max :flt:`f`

      Set the maximum edge length to :flt:`f`.

   .. kwd:: Radial

      Add a center vertex to all faces.

   .. kwd:: Radial-8

      Add a center vertex and mid-edge vertices to all faces.

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

   The following example illustrates how :cmd:`block.face.triangulate` can be used

   .. seealso::

Line-by-Line

.. block face triangulate command

Start a command doc with a comment that is an exact spelling of the command, followed by two carriage returns. A command doc cannot start with the document title. [1]

``block face triangulate`` command
######################################

Put the title of the command in double tic marks ( `` ), use # for underlining, and follow the title with two carriage returns.

.. rubric:: Syntax
   :class: h2

Just put this next. Every command has this block in exactly this position.

.. command:: Block.face.Triangulate <keyword> <range>
   :module: blockface
   :kwlist:

This is the heart of the matter.

Line 1

The .. command:: directive is an ICG directive. For it to process a command correctly, the words of the command must be separated by a dot. The letter(s) of the command that are to be underlined in output must be capital letters.

Line 2

The :module: option is not optional. It must follow the main command signature. The value supplied here is needed to “gather” the commands for presentation in tables (indexes) elsewhere.

Line 3

The :kwlist: option does the magic of building the keyword list box on the command page (see the reference command page block face triangulate). Note this may be omitted, but only if either a) there are no keywords (it happens) or b) there are few enough (~2-5) that they will all display on page without scrolling. Note there is no defined standard for this — it is up to the author. And yes, the example page here would be a good case for omitting the option.

Triangulate faces of rigid blocks to increase the number of vertices on a
face.  If no keyword is supplied, the minimum number of triangles are
created.

The main description of the command follows. Look at the full listing above and note the indentation level of the description is aligned to the .. command:: directive.

It is good if the first line of this description is kept brief. Shoot for less than 40 words. The first line appears as a tooltip in index tables that list the command.

.. kwd:: Edge-Max :flt:`f`

   Set the maximum edge length to :flt:`f`.

.. kwd:: Radial

   Add a center vertex to all faces.

.. kwd:: Radial-8

   Add a center vertex and mid-edge vertices to all faces.

First level keywords are created by indenting three spaces from the .. command:: directive’s indention and using the ICG custom directive .. kwd::. As with .. command::, capitalize the letters of the keyword that are to be underlined. Put the description of the keyword immediately below the directive, at its indentation level.

Second, third, to n level keywords are added the same way, by placing a .. kwd:: directive at the indentation level of the parent keyword.

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

   The following example illustrates how :cmd:`block.face.triangulate` can be used

   .. seealso::

Please include this entire comment block as is. Most commands do not use it, but someday perhaps more of them will.

Further Examples

See the following documents if further examples are needed to copy. These pages illustrate more advanced handling of command docs.

[links to follow… ]

Endnotes