Stubgen command line options reference anchors

docs/source/stubgen.rst

@@ -1,5 +1,7 @@
 .. _stugen:
 
+.. program:: stubgen
+
 Automatic stub generation (stubgen)
 ===================================
 
@@ -66,7 +68,7 @@ generate stubs::
     $ stubgen foo.py bar.py
 
 This generates stubs ``out/foo.pyi`` and ``out/bar.pyi``. The default
-output directory ``out`` can be overridden with ``-o DIR``.
+output directory ``out`` can be overridden with :option:`-o DIR <-o>`.
 
 You can also pass directories, and stubgen will recursively search
 them for any ``.py`` files and generate stubs for all of them::
@@ -80,24 +82,26 @@ Alternatively, you can give module or package names using the
 
 Details of the options:
 
-``-m MODULE``, ``--module MODULE``
+.. option:: -m MODULE, --module MODULE
+
     Generate a stub file for the given module. This flag may be repeated
     multiple times.
 
     Stubgen *will not* recursively generate stubs for any submodules of
     the provided module.
 
-``-p PACKAGE``, ``--package PACKAGE``
+.. option:: -p PACKAGE, --package PACKAGE
+
     Generate stubs for the given package. This flag maybe repeated
     multiple times.
 
     Stubgen *will* recursively generate stubs for all submodules of
-    the provided package. This flag is identical to ``--module`` apart from
+    the provided package. This flag is identical to :option:`--module` apart from
     this behavior.
 
 .. note::
 
-   You can't mix paths and ``-m``/``-p`` options in the same stubgen
+   You can't mix paths and :option:`-m`/:option:`-p` options in the same stubgen
    invocation.
 
 Specifying how to generate stubs
@@ -110,50 +114,59 @@ stubs. By default, stubgen will also use mypy to perform light-weight
 semantic analysis of any Python modules. Use the following flags to
 alter the default behavior:
 
-``--no-import``
+.. option:: --no-import
+
     Don't try to import modules. Instead use mypy's normal search mechanism to find
     sources. This does not support C extension modules. This flag also disables
     runtime introspection functionality, which mypy uses to find the value of
     ``__all__``. As result the set of exported imported names in stubs may be
     incomplete. This flag is generally only useful when importing a module generates
     an error for some reason.
 
-``--parse-only``
+.. option:: --parse-only
+
     Don't perform semantic analysis of source files. This may generate
     worse stubs -- in particular, some module, class, and function aliases may
     be represented as variables with the ``Any`` type. This is generally only
     useful if semantic analysis causes a critical mypy error.
 
-``--doc-dir PATH``
+.. option:: --doc-dir PATH
+
     Try to infer better signatures by parsing .rst documentation in ``PATH``.
     This may result in better stubs, but currently it only works for C extension
     modules.
 
 Additional flags
 ****************
 
-``--py2``
+.. option:: --py2
+
     Run stubgen in Python 2 mode (the default is Python 3 mode).
 
-``--ignore-errors``
+.. option:: --ignore-errors
+
     If an exception was raised during stub generation, continue to process any
     remaining modules instead of immediately failing with an error.
 
-``--include-private``
+.. option:: --include-private
+
     Include definitions that are considered private in stubs (with names such
     as ``_foo`` with single leading underscore and no trailing underscores).
 
-``--search-path PATH``
+.. option:: --search-path PATH
+
     Specify module search directories, separated by colons (only used if
-    ``--no-import`` is given).
+    :option:`--no-import` is given).
+
+.. option:: --python-executable PATH
 
-``--python-executable PATH``
     Use Python interpreter at ``PATH`` for importing modules and runtime
-    introspection. This has no effect with ``--no-import``, and this only works
+    introspection. This has no effect with :option:`--no-import`, and this only works
     in Python 2 mode. In Python 3 mode the Python interpreter used to run stubgen
     will always be used.
 
-``-o PATH``, ``--output PATH``
+.. option:: -o PATH, --output PATH
+
     Change the output directory. By default the stubs are written in the
     ``./out`` directory. The output directory will be created if it doesn't
     exist. Existing stubs in the output directory will be overwritten without