added crossrefs to config values throughout the docs

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
-    <config-file-import-discovery>`.
+    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

docs/source/common_issues.rst

@@ -454,8 +454,8 @@ whose name is passed to :option:`--always-true <mypy --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 <mypy --python-version>` flag.
 For example, to verify your code typechecks if were run using Python 2, pass

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
 

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 <config-file>` using one of the two formats: relative or
+:ref:`config file <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:

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 <config-file>` to migrate your code
 to strict optional checking one file at a time, since there exists
-the :ref:`per-module flag <config-file-none-and-optional-handling>`
-``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,

docs/source/running_mypy.rst

@@ -200,8 +200,8 @@ If you are getting this error, try:
 
 3.  :ref:`Writing your own stub files <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 <config-file-import-discovery>`, 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 <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 <mypy --ignore-missing-imports>` command line flag or set
-    the ``ignore_missing_imports``
-    :ref:`config file option <config-file-import-discovery>` 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 <config-file-import-discovery>`,
+    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 <mypy -m>` 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 <config-file-import-discovery>`.
+- 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 <config-file-import-discovery>` 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.
 

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).