Mypy command line options crossreferencing (#7802)

hoefling · JukkaL · commit d7268ee3336a · 2019-10-28T15:29:02.000Z
This is the follow-up of #7784. All options verbatim texts and :ref: usages are replaced with the :option: role.
diff --git a/docs/source/additional_features.rst b/docs/source/additional_features.rst
@@ -286,7 +286,7 @@ run after starting or restarting the daemon.
 
 The mypy daemon requires extra fine-grained dependency data in
 the cache files which aren't included by default. To use caching with
-the mypy daemon, use the ``--cache-fine-grained`` option in your CI
+the mypy daemon, use the :option:`--cache-fine-grained <mypy --cache-fine-grained>` option in your CI
 build::
 
     $ mypy --cache-fine-grained <args...>
@@ -326,7 +326,7 @@ at least if your codebase is hundreds of thousands of lines or more:
   network), the script can still fall back to a normal incremental build.
 
 * You can have multiple local cache directories for different local branches
-  using the ``--cache-dir`` option. If the user switches to an existing
+  using the :option:`--cache-dir <mypy --cache-dir>` option. If the user switches to an existing
   branch where downloaded cache data is already available, you can continue
   to use the existing cache data instead of redownloading the data.
 
diff --git a/docs/source/command_line.rst b/docs/source/command_line.rst
@@ -6,7 +6,7 @@ The mypy command line
 =====================
 
 This section documents mypy's command line interface. You can view
-a quick summary of the available flags by running ``mypy --help``.
+a quick summary of the available flags by running :option:`mypy --help`.
 
 .. note::
 
@@ -44,7 +44,7 @@ for full details, see :ref:`running-mypy`.
     package. This flag is identical to :option:`--module` apart from this
     behavior.
 
-.. option -c PROGRAM_TEXT, --command PROGRAM_TEXT
+.. option:: -c PROGRAM_TEXT, --command PROGRAM_TEXT
 
     Asks mypy to type check the provided string as a program.
 
@@ -523,7 +523,7 @@ of the above sections.
 .. option:: --strict
 
     This flag mode enables all optional error checking flags.  You can see the
-    list of flags enabled by strict mode in the full ``mypy --help`` output.
+    list of flags enabled by strict mode in the full :option:`mypy --help` output.
 
     Note: the exact list of flags enabled by running :option:`--strict` may change
     over time.
diff --git a/docs/source/common_issues.rst b/docs/source/common_issues.rst
@@ -31,7 +31,7 @@ flagged as an error.
   return type) are not type-checked, and even the most blatant type
   errors (e.g. ``2 + 'a'``) pass silently.  The solution is to add
   annotations. Where that isn't possible, functions without annotations
-  can be checked using ``--check-untyped-defs``.
+  can be checked using :option:`--check-untyped-defs <mypy --check-untyped-defs>`.
 
   Example:
 
@@ -73,17 +73,17 @@ flagged as an error.
   <https://github.com/python/typeshed/issues/285>`_ for the reason).
 
 - **Some imports may be silently ignored**.  Another source of
-  unexpected ``Any`` values are the :ref:`"--ignore-missing-imports"
-  <ignore-missing-imports>` and :ref:`"--follow-imports=skip"
-  <follow-imports>` flags.  When you use ``--ignore-missing-imports``,
+  unexpected ``Any`` values are the :option:`--ignore-missing-imports
+  <mypy --ignore-missing-imports>` and :option:`--follow-imports=skip
+  <mypy --follow-imports>` flags.  When you use :option:`--ignore-missing-imports <mypy --ignore-missing-imports>`,
   any imported module that cannot be found is silently replaced with
-  ``Any``.  When using ``--follow-imports=skip`` the same is true for
+  ``Any``.  When using :option:`--follow-imports=skip <mypy --follow-imports>` the same is true for
   modules for which a ``.py`` file is found but that are not specified
   on the command line.  (If a ``.pyi`` stub is found it is always
   processed normally, regardless of the value of
-  ``--follow-imports``.)  To help debug the former situation (no
-  module found at all) leave out ``--ignore-missing-imports``; to get
-  clarity about the latter use ``--follow-imports=error``.  You can
+  :option:`--follow-imports <mypy --follow-imports>`.)  To help debug the former situation (no
+  module found at all) leave out :option:`--ignore-missing-imports <mypy --ignore-missing-imports>`; to get
+  clarity about the latter use :option:`--follow-imports=error <mypy --follow-imports>`.  You can
   read up about these and other useful flags in :ref:`command-line`.
 
 - **A function annotated as returning a non-optional type returns 'None'
@@ -418,7 +418,7 @@ Example:
 
 Some other expressions exhibit similar behavior; in particular,
 :py:data:`~typing.TYPE_CHECKING`, variables named ``MYPY``, and any variable
-whose name is passed to ``--always-true`` or ``--always-false``.
+whose name is passed to :option:`--always-true <mypy --always-true>` or :option:`--always-false <mypy --always-false>`.
 (However, ``True`` and ``False`` are not treated specially!)
 
 .. note::
@@ -431,14 +431,14 @@ 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``.
 
-To target a different Python version, use the ``--python-version X.Y`` flag.
+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
-in ``--python-version 2.7`` from the command line. Note that you do not need
+in :option:`--python-version 2.7 <mypy --python-version>` from the command line. Note that you do not need
 to have Python 2.7 installed to perform this check.
 
-To target a different operating system, use the ``--platform PLATFORM`` flag.
+To target a different operating system, use the :option:`--platform PLATFORM <mypy --platform>` flag.
 For example, to verify your code typechecks if it were run in Windows, pass
-in ``--platform win32``. See the documentation for :py:data:`sys.platform`
+in :option:`--platform win32 <mypy --platform>`. See the documentation for :py:data:`sys.platform`
 for examples of valid platform parameters.
 
 .. _reveal-type:
diff --git a/docs/source/config_file.rst b/docs/source/config_file.rst
@@ -7,11 +7,11 @@ Mypy supports reading configuration settings from a file.  By default
 it uses the file ``mypy.ini`` with fallback to ``setup.cfg`` in the current
 directory, then ``$XDG_CONFIG_HOME/mypy/config``, then
 ``~/.config/mypy/config``, and finally ``.mypy.ini`` in the user home directory
-if none of them are found; the ``--config-file`` command-line flag can be used
-to read a different file instead (see :ref:`--config-file <config-file-flag>`).
+if none of them are found; the :option:`--config-file <mypy --config-file>` command-line flag can be used
+to read a different file instead (see :ref:`config-file-flag`).
 
 It is important to understand that there is no merging of configuration
-files, as it would lead to ambiguity.  The ``--config-file`` flag
+files, as it would lead to ambiguity.  The :option:`--config-file <mypy --config-file>` flag
 has the highest precedence and must be correct; otherwise mypy will report
 an error and exit.  Without command line option, mypy will look for defaults,
 but will use only one of them.  The first one to read is ``mypy.ini``,
@@ -134,7 +134,7 @@ This config file specifies three global options in the ``[mypy]`` section. These
 options will:
 
 1.  Type-check your entire project assuming it will be run using Python 2.7.
-    (This is equivalent to using the ``--python-version 2.7`` or ``--2`` flag).
+    (This is equivalent to using the :option:`--python-version 2.7 <mypy --python-version>` or :option:`-2 <mypy -2>` flag).
 
 2.  Report an error whenever a function returns a value that is inferred
     to have type ``Any``.
diff --git a/docs/source/error_code_list2.rst b/docs/source/error_code_list2.rst
@@ -18,7 +18,7 @@ error codes that are enabled by default.
 Check that type arguments exist [type-arg]
 ------------------------------------------
 
-If you use ``--disallow-any-generics``, mypy requires that each generic
+If you use :option:`--disallow-any-generics <mypy --disallow-any-generics>`, mypy requires that each generic
 type has values for each type argument. For example, the types ``List`` or
 ``dict`` would be rejected. You should instead use types like ``List[int]`` or
 ``Dict[str, int]``. Any omitted generic type arguments get implicit ``Any``
@@ -39,7 +39,7 @@ Example:
 Check that every function has an annotation [no-untyped-def]
 ------------------------------------------------------------
 
-If you use ``--disallow-untyped-defs``, mypy requires that all functions
+If you use :option:`--disallow-untyped-defs <mypy --disallow-untyped-defs>`, mypy requires that all functions
 have annotations (either a Python 3 annotation or a type comment).
 
 Example:
@@ -67,7 +67,7 @@ Example:
 Check that cast is not redundant [redundant-cast]
 -------------------------------------------------
 
-If you use ``--warn-redundant-casts``, mypy will generate an error if the source
+If you use :option:`--warn-redundant-casts <mypy --warn-redundant-casts>`, mypy will generate an error if the source
 type of a cast is the same as the target type.
 
 Example:
@@ -87,7 +87,7 @@ Example:
 Check that comparisons are overlapping [comparison-overlap]
 -----------------------------------------------------------
 
-If you use ``--strict-equality``, mypy will generate an error if it
+If you use :option:`--strict-equality <mypy --strict-equality>`, mypy will generate an error if it
 thinks that a comparison operation is always true or false. These are
 often bugs. Sometimes mypy is too picky and the comparison can
 actually be useful. Instead of disabling strict equality checking
@@ -118,7 +118,7 @@ literal:
 Check that no untyped functions are called [no-untyped-call]
 ------------------------------------------------------------
 
-If you use ``--disallow-untyped-calls``, mypy generates an error when you
+If you use :option:`--disallow-untyped-calls <mypy --disallow-untyped-calls>`, mypy generates an error when you
 call an unannotated function in an annotated function.
 
 Example:
@@ -138,7 +138,7 @@ Example:
 Check that function does not return Any value [no-any-return]
 -------------------------------------------------------------
 
-If you use ``--warn-return-any``, mypy generates an error if you return a
+If you use :option:`--warn-return-any <mypy --warn-return-any>`, mypy generates an error if you return a
 value with an ``Any`` type in a function that is annotated to return a
 non-``Any`` value.
 
@@ -158,7 +158,7 @@ Example:
 Check that types have no Any components due to missing imports [no-any-unimported]
 ----------------------------------------------------------------------------------
 
-If you use ``--disallow-any-unimported``, mypy generates an error if a component of
+If you use :option:`--disallow-any-unimported <mypy --disallow-any-unimported>`, mypy generates an error if a component of
 a type becomes ``Any`` because mypy couldn't resolve an import. These "stealth"
 ``Any`` types can be surprising and accidentally cause imprecise type checking.
 
diff --git a/docs/source/error_codes.rst b/docs/source/error_codes.rst
@@ -23,7 +23,7 @@ Error codes may change in future mypy releases.
 Displaying error codes
 ----------------------
 
-Error codes are not displayed by default.  Use ``--show-error-codes``
+Error codes are not displayed by default.  Use :option:`--show-error-codes <mypy --show-error-codes>`
 to display error codes. Error codes are shown inside square brackets:
 
 .. code-block:: text
@@ -43,7 +43,7 @@ codes on individual lines using this comment.
 .. note::
 
   There are command-line flags and config file settings for enabling
-  certain optional error codes, such as ``--disallow-untype-defs``,
+  certain optional error codes, such as :option:`--disallow-untyped-defs <mypy --disallow-untyped-defs>`,
   which enables the ``no-untyped-def`` error code.
 
 This example shows how to ignore an error about an imported name mypy
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -90,7 +90,7 @@ How do I type check my Python 2 code?
 
 You can use a :pep:`comment-based function annotation syntax
 <484#suggested-syntax-for-python-2-7-and-straddling-code>`
-and use the ``--py2`` command-line option to type check your Python 2 code.
+and use the :option:`--py2 <mypy --py2>` command-line option to type check your Python 2 code.
 You'll also need to install ``typing`` for Python 2 via ``pip install typing``.
 
 Is mypy free?
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -42,7 +42,7 @@ to your code to take full advantage of mypy. See the section below for details.
 .. note::
 
   Although you must install Python 3 to run mypy, mypy is fully capable of
-  type checking Python 2 code as well: just pass in the ``--py2`` flag. See
+  type checking Python 2 code as well: just pass in the :option:`--py2 <mypy --py2>` flag. See
   :ref:`python2` for more details.
 
   .. code-block:: shell
@@ -102,7 +102,7 @@ when you are prototyping a new feature, it may be convenient to initially implem
 the code using dynamic typing and only add type hints later once the code is more stable.
 
 Once you are finished migrating or prototyping your code, you can make mypy warn you
-if you add a dynamic function by mistake by using the ``--disallow-untyped-defs``
+if you add a dynamic function by mistake by using the :option:`--disallow-untyped-defs <mypy --disallow-untyped-defs>`
 flag. See :ref:`command-line` for more information on configuring mypy.
 
 .. note::
@@ -333,11 +333,11 @@ mypy behaves: see :ref:`command-line` for more details.
 For example, suppose you want to make sure *all* functions within your
 codebase are using static typing and make mypy report an error if you
 add a dynamically-typed function by mistake. You can make mypy do this
-by running mypy with the ``--disallow-untyped-defs`` flag.
+by running mypy with the :option:`--disallow-untyped-defs <mypy --disallow-untyped-defs>` flag.
 
-Another potentially useful flag is ``--strict``, which enables many
+Another potentially useful flag is :option:`--strict <mypy --strict>`, which enables many
 (though not all) of the available strictness options -- including
-``--disallow-untyped-defs``.
+:option:`--disallow-untyped-defs <mypy --disallow-untyped-defs>`.
 
 This flag is mostly useful if you're starting a new project from scratch
 and want to maintain a high degree of type safety from day one. However,
diff --git a/docs/source/installed_packages.rst b/docs/source/installed_packages.rst
@@ -19,15 +19,15 @@ By default, mypy searches for packages installed for the Python executable
 running mypy. It is highly unlikely you want this situation if you have
 installed typed packages in another Python's package directory.
 
-Generally, you can use the ``--python-version`` flag and mypy will try to find
+Generally, you can use the :option:`--python-version <mypy --python-version>` flag and mypy will try to find
 the correct package directory. If that fails, you can use the
-``--python-executable`` flag to point to the exact executable, and mypy will
+:option:`--python-executable <mypy --python-executable>` flag to point to the exact executable, and mypy will
 find packages installed for that Python executable.
 
 Note that mypy does not support some more advanced import features, such as zip
 imports and custom import hooks.
 
-If you do not want to use typed packages, use the ``--no-site-packages`` flag
+If you do not want to use typed packages, use the :option:`--no-site-packages <mypy --no-site-packages>` flag
 to disable searching.
 
 Note that stub-only packages (defined in :pep:`PEP 561: Stub-only Packages
diff --git a/docs/source/kinds_of_types.rst b/docs/source/kinds_of_types.rst
@@ -402,7 +402,7 @@ case you should add an explicit ``Optional[...]`` annotation (or type comment).
     ``Optional[...]`` *does not* mean a function argument with a default value.
     However, if the default value of an argument is ``None``, you can use
     an optional type for the argument, but it's not enforced by default.
-    You can use the ``--no-implicit-optional`` command-line option to stop
+    You can use the :option:`--no-implicit-optional <mypy --no-implicit-optional>` command-line option to stop
     treating arguments with a ``None`` default value as having an implicit
     ``Optional[...]`` type. It's possible that this will become the default
     behavior in the future.
@@ -418,7 +418,7 @@ the Java ``null``). In this mode ``None`` is also valid for primitive
 types such as ``int`` and ``float``, and :py:data:`~typing.Optional` types are
 not required.
 
-The mode is enabled through the ``--no-strict-optional`` command-line
+The mode is enabled through the :option:`--no-strict-optional <mypy --no-strict-optional>` command-line
 option. In mypy versions before 0.600 this was the default mode. You
 can enable this option explicitly for backward compatibility with
 earlier mypy versions, in case you don't want to introduce optional
diff --git a/docs/source/more_types.rst b/docs/source/more_types.rst
@@ -535,7 +535,7 @@ type hints provided on the implementation. For example, in the
 argument list ``index: Union[int, slice]`` and a return type of
 ``Union[T, Sequence[T]]``. If there are no annotations on the
 implementation, then the body is not type checked. If you want to
-force mypy to check the body anyways, use the ``--check-untyped-defs``
+force mypy to check the body anyways, use the :option:`--check-untyped-defs <mypy --check-untyped-defs>`
 flag (:ref:`more details here <untyped-definitions-and-calls>`).
 
 The variants must also also be compatible with the implementation
diff --git a/docs/source/mypy_daemon.rst b/docs/source/mypy_daemon.rst
@@ -1,5 +1,7 @@
 .. _mypy_daemon:
 
+.. program:: dmypy
+
 Mypy daemon (mypy server)
 =========================
 
@@ -41,8 +43,8 @@ will always run on the current host. Example::
     dmypy run -- --follow-imports=error prog.py pkg1/ pkg2/
 
 .. note::
-   You'll need to use either the ``--follow-imports=error`` or the
-   ``--follow-imports=skip`` option with dmypy because the current
+   You'll need to use either the :option:`--follow-imports=error <mypy --follow-imports>` or the
+   :option:`--follow-imports=skip <mypy --follow-imports>` option with dmypy because the current
    implementation can't follow imports.
    See :ref:`follow-imports` for details on how these work.
    You can also define these using a
@@ -53,7 +55,7 @@ configuration or mypy version changes.
 
 You need to provide all files or directories you want to type check
 (other than stubs) as arguments. This is a result of the
-``--follow-imports`` restriction mentioned above.
+:option:`--follow-imports <mypy --follow-imports>` restriction mentioned above.
 
 The initial run will process all the code and may take a while to
 finish, but subsequent runs will be quick, especially if you've only
@@ -95,8 +97,8 @@ command-specific options.
 Limitations
 ***********
 
-* You have to use either the ``--follow-imports=error`` or
-  the ``--follow-imports=skip`` option because of an implementation
+* You have to use either the :option:`--follow-imports=error <mypy --follow-imports>` or
+  the :option:`--follow-imports=skip <mypy --follow-imports>` option because of an implementation
   limitation. This can be defined
   through the command line or through a
   :ref:`configuration file <config-file>`.
diff --git a/docs/source/python2.rst b/docs/source/python2.rst
@@ -8,7 +8,7 @@ annotations are given in comments, since the function annotation
 syntax was introduced in Python 3. The comment-based syntax is
 specified in :pep:`484`.
 
-Run mypy in Python 2 mode by using the ``--py2`` option::
+Run mypy in Python 2 mode by using the :option:`--py2 <mypy --py2>` option::
 
     $ mypy --py2 program.py
 
diff --git a/docs/source/running_mypy.rst b/docs/source/running_mypy.rst
diff --git a/docs/source/stubs.rst b/docs/source/stubs.rst
