search

sphinx-doc / sphinx

The Sphinx documentation generator
https://www.sphinx-doc.org/
Other
6.54k stars 2.12k forks source link

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

Closed shimizukawa closed 9 years ago

shimizukawa commented 9 years ago

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.

shimizukawa commented 9 years ago

From Georg Brandl on 2014-01-22 16:26:04+00:00

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.

shimizukawa commented 9 years ago

From Georg Brandl on 2014-01-22 16:41:57+00:00

Closes #1357: Option names documented by :rst:dir:option are now again allowed to not start with a dash or slash, and referencing them will work correctly.

→ <<cset 2acaf03270ce0235397c3b9a81f51f22a0fa626b>>