Issues

Issue #1357 resolved

new warnings in Sphinx 1.2.1 with .. option:: directive

Anonymous created an issue

I looked at Sphinx 1.2.1 to see if our project (OpenMDAO, which is found at openmdao.org) should move to it. (I just edit the docs & update Sphinx via a branch; I'm not a developer.) When I built the docs on a branch using 1.2.1, I got 3 new warnings not present when I built with v1.2. They are:

/OpenMDAO/dev/pziegfel/OpenMDAO-Framework/docs/plugin-guide/module_plugin.rst:32: WARNING: Malformed option description u'dist_name', should look like "-opt args", "--opt args" or "/opt args" /OpenMDAO/dev/pziegfel/OpenMDAO-Framework/docs/plugin-guide/module_plugin.rst:385: WARNING: Malformed option description u'dist_directory', should look like "-opt args", "--opt args" or "/opt args" /OpenMDAO/dev/pziegfel/OpenMDAO-Framework/docs/plugin-guide/module_plugin.rst:401: WARNING: Malformed option description u'plugin_dist_name', should look like "-opt args", "--opt args" or "/opt args"

Here is the doc (between lines of asterisks) where the first warning occurs. The other two :


Getting Started Quickly

To create the initial directory structure for our plugin distribution, we use the plugin quickstart command.

.. program:: plugin_quickstart

::

plugin quickstart dist_name [-v version [-c class_name [-g plugin_group [-d dest_directory]]]]

.. option:: dist_name

The name of the distribution we want to create.

.. option:: -v

Version id of the distribution. Defaults to 0.1.

.. option:: -c

Name of the plugin class. By default the plugin class has the same name as the distribution except the first letter is capitalized.

.. option:: -g

Plugin group. Defaults to openmdao.component. Other possible values are: openmdao.driver and openmdao.variable.


The first warning refers to the text above for the first option ".. option:: dist_name". As you can see, options following the first one are fine. (The other two places where warnings are cited are similar.)

I asked our lead developer about this. He said they use Argparse (recommended command-line parsing module in the Python standard library), which allows that format to include a hyphen (minus sign) or not. I don't know what changed, but since Argparse allows this format, the developer thinks Sphinx is being too restrictive. Thanks.

Comments (3)

  1. Georg Brandl repo owner

    Hmm, yes, the old dispute "what is an option". In getopt terminology you have "options" (things starting with "-") and "arguments" (all others).

    But since there is no "argument" directive, I agree that we should allow both.

  2. Log in to comment