Use ... to format code within normal text

Author: JukkaL

docs/source/additional_features.rst

@@ -6,4 +6,4 @@ including the following:
 
 - inheritance between generic classes
 - compatibility and subtyping of generic types, including covariance of generic types
-- super()
+- ``super()``

docs/source/basics.rst

@@ -23,8 +23,8 @@ reports type errors within the function):
    def greeting(name: str) -> str:
        return 'Hello, {}'.format(name)
 
-A None return type indicates a function that does not explicitly
-return a value. Using a None result in a statically typed context
+A ``None`` return type indicates a function that does not explicitly
+return a value. Using a ``None`` result in a statically typed context
 results in a type check error:
 
 .. code-block:: python
@@ -38,7 +38,7 @@ The typing module
 *****************
 
 We cheated a bit in the above examples: a module is type checked only
-if it imports the module typing. Here is a complete statically typed
+if it imports the module ``typing``. Here is a complete statically typed
 example from the previous section:
 
 .. code-block:: python
@@ -48,9 +48,9 @@ example from the previous section:
    def greeting(name: str) -> str:
        return 'Hello, {}'.format(name)
 
-The typing module contains many definitions that are useful in
-statically typed code. You can also use from ... import to import them
-(we'll explain Iterable later in this document):
+The ``typing`` module contains many definitions that are useful in
+statically typed code. You can also use ``from ... import`` to import
+them (we'll explain Iterable later in this document):
 
 .. code-block:: python
 
@@ -60,11 +60,11 @@ statically typed code. You can also use from ... import to import them
        for name in names:
            print('Hello, {}'.format(name))
 
-For brevity, we often omit the typing import in code examples, but you
-should always include it in modules that contain statically typed
+For brevity, we often omit the ``typing`` import in code examples, but
+you should always include it in modules that contain statically typed
 code.
 
-You can still have dynamically typed functions in modules that import typing:
+You can still have dynamically typed functions in modules that import ``typing``:
 
 .. code-block:: python
 

docs/source/builtin_types.rst

@@ -17,18 +17,18 @@ These are examples of some of the most common built-in types:
    Sequence[bool] # sequence of booleans
    Any            # dynamically typed value
 
-The type Any and type constructors List, Dict, Iterable and Sequence
-are defined in the typing module.
+The type ``Any`` and type constructors ``List``, ``Dict``,
+``Iterable`` and ``Sequence`` are defined in the ``typing`` module.
 
-The type Dict is a *generic* class, signified by type arguments within
-[...]. For example, Dict[int, str] is a dictionary from integers to
-strings and and Dict[Any, Any] is a dictionary of dynamically typed
-(arbitrary) values and keys. List is another generic class. Dict and
-List are aliases for the built-ins dict and list, respectively.
+The type ``Dict`` is a *generic* class, signified by type arguments within
+``[...]``. For example, ``Dict[int, str]`` is a dictionary from integers to
+strings and and ``Dict[Any, Any]`` is a dictionary of dynamically typed
+(arbitrary) values and keys. ``List`` is another generic class. ``Dict`` and
+``List`` are aliases for the built-ins ``dict`` and ``list``, respectively.
 
-Iterable and Sequence are generic abstract base classes that
-correspond to Python protocols. For example, a str object is valid
-when Iterable[str] or Sequence[str] is expected. Note that even though
-they are similar to abstract base classes defined in abc.collections
-(formerly collections), they are not identical, since the built-in
+``Iterable`` and ``Sequence`` are generic abstract base classes that
+correspond to Python protocols. For example, a ``str`` object is valid
+when ``Iterable[str]`` or ``Sequence[str]`` is expected. Note that even though
+they are similar to abstract base classes defined in ``abc.collections``
+(formerly ``collections``), they are not identical, since the built-in
 collection type objects do not support indexing.

docs/source/casts.rst

@@ -5,7 +5,7 @@ Mypy supports type casts that are usually used to coerce a statically
 typed value to a subtype. Unlike languages such as Java or C#,
 however, mypy casts are only used as hints for the type checker when
 using Python semantics, and they have no runtime effect. Use the
-function cast to perform a cast:
+function ``cast`` to perform a cast:
 
 .. code-block:: python
 
@@ -23,10 +23,14 @@ casts being checked at runtime. Use an assertion if you want to
 perform an actual runtime check. Casts are used to silence spurious
 type checker warnings.
 
-You don't need a cast for expressions with type Any, of when assigning
-to a variable with type Any, as was explained earlier.
+You don't need a cast for expressions with type ``Any``, of when
+assigning to a variable with type ``Any``, as was explained earlier.
 
-You can cast to a dynamically typed value by just calling Any:
+Any() as a cast
+***************
+
+You can cast to a dynamically typed value by just calling ``Any``;
+this is equivalent to ``cast(Any, ...)`` but shorter:
 
 .. code-block:: python
 

docs/source/class_basics.rst

@@ -19,10 +19,10 @@ initialized within the class. Mypy infers the types of attributes:
    a.x = 2       # OK
    a.y = 3       # Error: A has no attribute y
 
-This is a bit like each class having an implicitly defined __slots__
-attribute. In Python semantics this is only enforced during type
-checking: at runtime we use standard Python semantics. You can
-selectively define a class as *dynamic*; dynamic classes have
+This is a bit like each class having an implicitly defined
+``__slots__`` attribute. In Python semantics this is only enforced
+during type checking: at runtime we use standard Python semantics. You
+can selectively define a class as *dynamic*; dynamic classes have
 Python-like compile-time semantics, and they allow you to assign to
 arbitrary attributes anywhere in a program without the type checker
 complaining:
@@ -45,8 +45,8 @@ use dynamic classes when you really need them.
 
    Dynamic classes are not implemented in the current mypy version.
 
-You can declare variables in the class body explicitly using Undefined
-or a type comment:
+You can declare variables in the class body explicitly using
+``Undefined`` or a type comment:
 
 .. code-block:: python
 
@@ -73,7 +73,7 @@ in a method:
            self.y = 0 # type: Any            # OK
 
 You can only define an instance variable within a method if you assign
-to it explicitly using self:
+to it explicitly using ``self``:
 
 .. code-block:: python
 
@@ -110,8 +110,8 @@ override has a compatible signature:
 .. note::
 
    You can also vary return types **covariantly** in overriding. For
-   example, you could override the return type 'object' with a subtype
-   such as 'int'.
+   example, you could override the return type ``object`` with a subtype
+   such as ``int``.
 
 You can also override a statically typed method with a dynamically
 typed one. This allows dynamically typed code to override methods
@@ -141,9 +141,10 @@ Abstract base classes and multiple inheritance
 **********************************************
 
 Mypy uses Python abstract base classes for protocol types. There are
-several built-in abstract base classes types (for example, Sequence,
-Iterable and Iterator). You can define abstract base classes using the
-abc.ABCMeta metaclass and the abc.abstractmethod function decorator.
+several built-in abstract base classes types (for example,
+``Sequence``, ``Iterable`` and ``Iterator``). You can define abstract
+base classes using the ``abc.ABCMeta`` metaclass and the
+``abc.abstractmethod`` function decorator.
 
 .. code-block:: python
 

docs/source/common_issues.rst

@@ -42,7 +42,7 @@ can make your code difficult to understand.
 Second, each name within a function only has a single type. You can
 reuse for loop indices etc., but if you want to use a variable with
 multiple types within a single function, you may need to declare it
-with the Any type.
+with the ``Any`` type.
 
 .. code-block:: python
 
@@ -77,8 +77,8 @@ above example:
    ...
    shape = Triangle()               # OK
 
-Fourth, if you use isinstance tests or other kinds of runtime type
-tests, you may have to add casts (this is similar to instanceof tests
+Fourth, if you use ``isinstance()`` tests or other kinds of runtime type
+tests, you may have to add casts (this is similar to ``instanceof`` tests
 in Java):
 
 .. code-block:: python
@@ -89,18 +89,19 @@ in Java):
            n += 1    # o += 1 would be an error
            ...
 
-Note that the object type used in the above example is similar to
-Object in Java: it only supports operations defined for all objects,
-such as equality and isinstance(). The type Any, in contrast, supports
-all operations, even if they may fail at runtime. The cast above would
-have been unnecessary if the type of o was Any.
-
-Some consider casual use of isinstance tests a sign of bad programming
-style. Often a method override or an overloaded function is a cleaner
-way of implementing functionality that depends on the runtime types of
-values. However, use whatever techniques that work for you. Sometimes
-isinstance tests *are* the cleanest way of implementing a piece of
-functionality.
+Note that the ``object`` type used in the above example is similar to
+``Object`` in Java: it only supports operations defined for all
+objects, such as equality and ``isinstance()``. The type ``Any``, in
+contrast, supports all operations, even if they may fail at
+runtime. The cast above would have been unnecessary if the type of
+``o`` was ``Any``.
+
+Some consider casual use of ``isinstance()`` tests a sign of bad
+programming style. Often a method override or an overloaded function
+is a cleaner way of implementing functionality that depends on the
+runtime types of values. However, use whatever techniques that work
+for you. Sometimes isinstance tests *are* the cleanest way of
+implementing a piece of functionality.
 
 Type inference in mypy is designed to work well in common cases, to be
 predictable and to let the type checker give useful error

docs/source/conf.py

@@ -262,3 +262,5 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
+
+rst_prolog = '.. |...| unicode:: U+2026   .. ellipsis\n'

docs/source/dynamic_typing.rst

@@ -6,7 +6,7 @@ explicit return type are dynamically typed (operations are checked at
 runtime). Code outside functions is statically typed by default, and
 types of variables are inferred. This does usually the right thing,
 but you can also make any variable dynamically typed by defining it
-explicitly with the type Any:
+explicitly with the type ``Any``:
 
 .. code-block:: python
 
@@ -17,8 +17,8 @@ explicitly with the type Any:
    s = 'x'               # Type check error
    d = 'x'               # OK
 
-Alternatively, you can use the Undefined construct to define
-dynamically typed variables, as Any can be used anywhere any other
+Alternatively, you can use the ``Undefined`` construct to define
+dynamically typed variables, as ``Any`` can be used anywhere any other
 type is valid:
 
 .. code-block:: python
@@ -29,7 +29,7 @@ type is valid:
    d = 1   # OK
    d = 'x' # OK
 
-Additionally, if you don't import the typing module in a file, all
+Additionally, if you don't import the ``typing`` module in a file, all
 code outside functions will be dynamically typed by default, and the
 file is not type checked at all. This mode makes it easy to include
 existing Python code that is not trivially compatible with static
@@ -38,4 +38,4 @@ typing.
 .. note::
 
    The current mypy version type checks all modules, even those that
-   don't import typing. This will change in a future version.
+   don't import ``typing``. This will change in a future version.

docs/source/faq.rst

@@ -164,8 +164,7 @@ dynamic or 'patchable').
 How is mypy different from PyPy?
 ********************************
 
-*This answer relates to PyPy as a Python implementation. See also the
- answer related to RPython below.*
+*This answer relates to PyPy as a Python implementation. See also the answer related to RPython below.*
 
 Mypy and PyPy are orthogonal. Mypy does static type checking, i.e. it
 is basically a linter, but static typing has no runtime effect,

docs/source/function_overloading.rst

@@ -39,4 +39,4 @@ programmer.
 
    As generic type variables are erased at runtime, an overloaded
    function cannot dispatch based on a generic type argument,
-   e.g. List[int] versus List[str].
+   e.g. ``List[int]`` versus ``List[str]``.

docs/source/generics.rst

@@ -6,8 +6,8 @@ Defining generic classes
 
 The built-in collection classes are generic classes. Generic types
 have one or more type parameters, which can be arbitrary types. For
-example, Dict]int, str] has the type parameters int and str, and
-List[int] has a type parameter int.
+example, ``Dict[int, str]`` has the type parameters ``int`` and
+``str``, and ``List[int]`` has a type parameter ``int``.
 
 Programs can also define new generic classes. Here is a very simple
 generic class that represents a stack:
@@ -31,10 +31,10 @@ generic class that represents a stack:
        def empty(self) -> bool:
            return not self.items
 
-The Stack class can be used to represent a stack of any type:
-Stack[int], Stack[Tuple[int, str]], etc.
+The ``Stack`` class can be used to represent a stack of any type:
+``Stack[int]``, ``Stack[Tuple[int, str]]``, etc.
 
-Using Stack is similar to built-in container types:
+Using ``Stack`` is similar to built-in container types:
 
 .. code-block:: python
 
@@ -54,31 +54,31 @@ Type inference works for user-defined generic types as well:
 Generic class internals
 ***********************
 
-You may wonder what happens at runtime when you index Stack. Actually,
-indexing Stack just returns Stack:
+You may wonder what happens at runtime when you index
+``Stack``. Actually, indexing ``Stack`` just returns ``Stack``:
 
 >>> print(Stack)
 <class '__main__.Stack'>
 >>> print(Stack[int])
 <class '__main__.Stack'>
 
-Note that built-in types list, dict and so on do not support indexing
-in Python. This is why we have the aliases List, Dict and so on in the
-typing module. Indexing these aliases just gives you the target class
-in Python, similar to Stack:
+Note that built-in types ``list``, ``dict`` and so on do not support
+indexing in Python. This is why we have the aliases ``List``, ``Dict``
+and so on in the ``typing`` module. Indexing these aliases just gives
+you the target class in Python, similar to ``Stack``:
 
 >>> from typing import List
 >>> List[int]
 <class 'list'>
 
 The above examples illustrate that type variables are erased at
-runtime when running in a Python VM. Generic Stack or list instances
-are just ordinary Python objects, and they have no extra runtime
-overhead or magic due to being generic, other than a metaclass that
-overloads the indexing operator. If you worry about the overhead
-introduced by the type indexing operation when constructing instances,
-you can often rewrite such code using a # type annotation, which has
-no runtime impact:
+runtime. Generic ``Stack`` or ``list`` instances are just ordinary
+Python objects, and they have no extra runtime overhead or magic due
+to being generic, other than a metaclass that overloads the indexing
+operator. If you worry about the overhead introduced by the type
+indexing operation when constructing instances, you can usually
+rewrite such code using a ``# type:`` annotation, which has no runtime
+impact:
 
 .. code-block:: python
 
@@ -118,7 +118,7 @@ return type is derived from the sequence item type. For example:
    s = first('foo')      # s has type str.
    n = first([1, 2, 3])  # n has type int.
 
-Note also that a single definition of a type variable (such as T
+Note also that a single definition of a type variable (such as ``T``
 above) can be used in multiple generic functions or classes. In this
 example we use the same type variable in two generic functions: