From efc98c53e647d0fc2f28eaa15b2b76139e276090 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oleg=20H=C3=B6fling?= Date: Thu, 24 Oct 2019 19:33:35 +0200 Subject: [PATCH] using option directive for stubgen command line options, adding refs in stubgen.rst MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Oleg Höfling --- docs/source/stubgen.rst | 45 ++++++++++++++++++++++++++--------------- 1 file changed, 29 insertions(+), 16 deletions(-) diff --git a/docs/source/stubgen.rst b/docs/source/stubgen.rst index 4f9f74c6a3c9..a1b1b25dfb44 100644 --- a/docs/source/stubgen.rst +++ b/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,7 +114,8 @@ 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 @@ -118,13 +123,15 @@ alter the default behavior: 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. @@ -132,28 +139,34 @@ alter the default behavior: 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