From 0ae41ae776f333d7d2a8d4e55d2d7681e63715b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Oleg=20H=C3=B6fling?= Date: Sat, 2 Nov 2019 21:48:07 +0100 Subject: [PATCH] added crossrefs to config values, added missing plugins config value, documented help option for stubgen Signed-off-by: oleg.hoefling --- docs/source/command_line.rst | 3 +-- docs/source/common_issues.rst | 4 ++-- docs/source/config_file.rst | 8 +++++++- docs/source/extending_mypy.rst | 5 ++++- docs/source/kinds_of_types.rst | 4 ++-- docs/source/running_mypy.rst | 26 +++++++++++++------------- docs/source/stubgen.rst | 8 ++++++-- 7 files changed, 35 insertions(+), 23 deletions(-) diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst index 9cd8ed6cd900..10760f418026 100644 --- a/docs/source/command_line.rst +++ b/docs/source/command_line.rst @@ -108,8 +108,7 @@ imports. prefers "classic" packages over namespace packages) along the module search path -- this is primarily set from the source files passed on the command line, the ``MYPYPATH`` environment variable, - and the :ref:`mypy_path config option - `. + and the :confval:`mypy_path` config option. Note that this only affects import discovery -- for modules and packages explicitly passed on the command line, mypy still diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst index 8b326408abc6..3867e168bd6a 100644 --- a/docs/source/common_issues.rst +++ b/docs/source/common_issues.rst @@ -454,8 +454,8 @@ whose name is passed to :option:`--always-true ` or :option: check to a variable. This may change in future versions of mypy. By default, mypy will use your current version of Python and your current -operating system as default values for ``sys.version_info`` and -``sys.platform``. +operating system as default values for :py:data:`sys.version_info` and +:py:data:`sys.platform`. To target a different Python version, use the :option:`--python-version X.Y ` flag. For example, to verify your code typechecks if were run using Python 2, pass diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst index 6e9593716924..f45eceacbe67 100644 --- a/docs/source/config_file.rst +++ b/docs/source/config_file.rst @@ -679,12 +679,18 @@ Advanced options These options may only be set in the global section (``[mypy]``). +.. confval:: plugins + + :type: comma-separated list of strings + + A comma-separated list of mypy plugins. See :ref:`extending-mypy-using-plugins`. + .. confval:: pdb :type: boolean :default: False - Invokes pdb on fatal error. + Invokes :mod:`pdb` on fatal error. .. confval:: show_traceback diff --git a/docs/source/extending_mypy.rst b/docs/source/extending_mypy.rst index 679c9b24e5b8..43d16491f1f1 100644 --- a/docs/source/extending_mypy.rst +++ b/docs/source/extending_mypy.rst @@ -37,6 +37,9 @@ A trivial example of using the api is the following print('\nExit status:', result[2]) + +.. _extending-mypy-using-plugins: + Extending mypy using plugins **************************** @@ -69,7 +72,7 @@ Configuring mypy to use plugins ******************************* Plugins are Python files that can be specified in a mypy -:ref:`config file ` using one of the two formats: relative or +:ref:`config file ` using the :confval:`plugins` option and one of the two formats: relative or absolute path to the plugin file, or a module name (if the plugin is installed using ``pip install`` in the same virtual environment where mypy is running). The two formats can be mixed, for example: diff --git a/docs/source/kinds_of_types.rst b/docs/source/kinds_of_types.rst index acb8a3edff72..ea78ca938a1f 100644 --- a/docs/source/kinds_of_types.rst +++ b/docs/source/kinds_of_types.rst @@ -437,8 +437,8 @@ this example -- it's not recommended if you can avoid it: However, making code "optional clean" can take some work! You can also use :ref:`the mypy configuration file ` to migrate your code to strict optional checking one file at a time, since there exists -the :ref:`per-module flag ` -``strict_optional`` to control strict optional mode. +the per-module flag +:confval:`strict_optional` to control strict optional mode. Often it's still useful to document whether a variable can be ``None``. For example, this function accepts a ``None`` argument, diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst index 69690afe906e..028f50d9862a 100644 --- a/docs/source/running_mypy.rst +++ b/docs/source/running_mypy.rst @@ -200,8 +200,8 @@ If you are getting this error, try: 3. :ref:`Writing your own stub files ` containing type hints for the library. You can point mypy at your type hints either by passing - them in via the command line, by using the ``files`` or ``mypy_path`` - :ref:`config file options `, or by + them in via the command line, by using the :confval:`files` or :confval:`mypy_path` + config file options, or by adding the location to the ``MYPYPATH`` environment variable. These stub files do not need to be complete! A good strategy is to use @@ -223,7 +223,7 @@ will continue to be of type ``Any``. 2. To suppress *all* missing import imports errors from a single library, add a section to your :ref:`mypy config file ` for that library setting - ``ignore_missing_imports`` to True. For example, suppose your codebase + :confval:`ignore_missing_imports` to True. For example, suppose your codebase makes heavy use of an (untyped) library named ``foobar``. You can silence all import errors associated with that library and that library alone by adding the following section to your config file:: @@ -240,8 +240,8 @@ will continue to be of type ``Any``. 3. To suppress *all* missing import errors for *all* libraries in your codebase, invoke mypy with the :option:`--ignore-missing-imports ` command line flag or set - the ``ignore_missing_imports`` - :ref:`config file option ` to True + the :confval:`ignore_missing_imports` + config file option to True in the *global* section of your mypy config file:: [mypy] @@ -275,8 +275,8 @@ this error, try: how you're invoking mypy accordingly. 3. Directly specifying the directory containing the module you want to - type check from the command line, by using the ``files`` or - ``mypy_path`` :ref:`config file options `, + type check from the command line, by using the :confval:`files` or + :confval:`mypy_path` config file options, or by using the ``MYPYPATH`` environment variable. Note: if the module you are trying to import is actually a *submodule* of @@ -309,7 +309,7 @@ even if the imported module is not a file you explicitly wanted mypy to check. For example, suppose we have two modules ``mycode.foo`` and ``mycode.bar``: the former has type hints and the latter does not. We run -``mypy -m mycode.foo`` and mypy discovers that ``mycode.foo`` imports +:option:`mypy -m mycode.foo ` and mypy discovers that ``mycode.foo`` imports ``mycode.bar``. How do we want mypy to type check ``mycode.bar``? We can configure the @@ -426,7 +426,7 @@ This is computed from the following items: - The ``MYPYPATH`` environment variable (a colon-separated list of directories). -- The ``mypy_path`` :ref:`config file option `. +- The :confval:`mypy_path` config file option. - The directories containing the sources given on the command line (see below). - The installed packages marked as safe for type checking (see @@ -470,15 +470,15 @@ Other advice and best practices ******************************* There are multiple ways of telling mypy what files to type check, ranging -from passing in command line arguments to using the ``files`` or ``mypy_path`` -:ref:`config file options ` to setting the +from passing in command line arguments to using the :confval:`files` or :confval:`mypy_path` +config file options to setting the ``MYPYPATH`` environment variable. However, in practice, it is usually sufficient to just use either -command line arguments or the ``files`` config file option (the two +command line arguments or the :confval:`files` config file option (the two are largely interchangeable). -Setting ``mypy_path``/``MYPYPATH`` is mostly useful in the case +Setting :confval:`mypy_path`/``MYPYPATH`` is mostly useful in the case where you want to try running mypy against multiple distinct sets of files that happen to share some common dependencies. diff --git a/docs/source/stubgen.rst b/docs/source/stubgen.rst index 38cd7b835b99..a58a022e6c67 100644 --- a/docs/source/stubgen.rst +++ b/docs/source/stubgen.rst @@ -53,7 +53,7 @@ The stubs will be much more useful if you add more precise type annotations, at least for the most commonly used functionality. The rest of this section documents the command line interface of stubgen. -Run ``stubgen --help`` for a quick summary of options. +Run :option:`stubgen --help` for a quick summary of options. .. note:: @@ -76,7 +76,7 @@ them for any ``.py`` files and generate stubs for all of them:: $ stubgen my_pkg_dir Alternatively, you can give module or package names using the -``-m`` or ``-p`` options:: +:option:`-m` or :option:`-p` options:: $ stubgen -m foo -m bar -p my_pkg_dir @@ -143,6 +143,10 @@ alter the default behavior: Additional flags **************** +.. option:: -h, --help + + Show help message and exit. + .. option:: --py2 Run stubgen in Python 2 mode (the default is Python 3 mode).