new warnings in Sphinx 1.2.1 with .. option:: directive
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
.. 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:
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.