Includes

Two directives splice another file into this one: .. include:: brings in reStructuredText, which is parsed as if it had been typed here, and .. literalinclude:: brings in a source file, which is shown verbatim.

Both read their file while parsing, so under Bazel the file has to be declared in the library's parse_data attribute. A file that is included must not also appear in srcs, or it would be published as a page of its own as well as being spliced in here.

Including reStructuredText

The whole of a fragment, parsed in place:

The text between the markers below is what a selective include picks up.

Every function in this example takes the same two parameters:

name

The thing to greet, as a string.

times

How often to repeat the greeting.

This closing paragraph is outside the markers, so a :start-after:/:end-before: include leaves it behind.

Selecting part of a fragment

The same fragment carries BEGIN/END markers, so a document can take just the part it wants. Note that the markers themselves stay out:

Every function in this example takes the same two parameters:

name

The thing to greet, as a string.

times

How often to repeat the greeting.

docutils' :start-line:/:end-line: select by index instead. They are 0-based and the end is exclusive — the one place in reStructuredText that counts from zero:

The text between the markers below is what a selective include picks up.

Including a file verbatim

:literal: shows the fragment's own markup rather than interpreting it, and :code: does the same with a language for highlighting:

Every function in this example takes the same two parameters:

``name``
   The thing to greet, as a string.

``times``
   How often to repeat the greeting.

Including source files

.. literalinclude:: takes a path as its argument and the language as an option, unlike .. code-block:::

"""A tiny module, shown by ``includes.rst`` via ``.. literalinclude::``."""

import sys


# [greet]

def greet(name: str, times: int = 1) -> str:
    """Return a greeting for ``name``, repeated ``times`` times."""
    line = f"Hello, {name}!"
    return "\n".join([line] * times)
# [/greet]



def main() -> int:
    print(greet("world"))
    return 0


if __name__ == "__main__":
    sys.exit(main())

With no :language: it inherits from the enclosing .. highlight::, exactly as a .. code-block:: with no argument does.

Selecting lines

:lines: takes numbers and ranges, and :lineno-match: numbers the result from the line it really starts at in the file:

7def greet(name: str, times: int = 1) -> str:
8    """Return a greeting for ``name``, repeated ``times`` times."""
9    line = f"Hello, {name}!"
10    return "\n".join([line] * times)
11# [/greet]

The marker comments in the file are the more maintainable way to say the same thing, since they survive an edit above them:

def greet(name: str, times: int = 1) -> str:
    """Return a greeting for ``name``, repeated ``times`` times."""
    line = f"Hello, {name}!"
    return "\n".join([line] * times)

Framing the excerpt

:prepend: and :append: add lines around the selection, which is how an excerpt from the middle of a file is made to stand on its own:

import sys
def greet(name: str, times: int = 1) -> str:
    """Return a greeting for ``name``, repeated ``times`` times."""
    line = f"Hello, {name}!"
    return "\n".join([line] * times)
# ... and so on

Showing a change

:diff: shows the patch between another file and this one, rather than either file's contents:

--- examples/shared/greeter_before.py

+++ examples/shared/greeter.py

@@ -4,9 +4,10 @@



 # [greet]
-def greet(name: str) -> str:

-    """Return a greeting for ``name``."""

-    return f"Hello, {name}!"

+def greet(name: str, times: int = 1) -> str:

+    """Return a greeting for ``name``, repeated ``times`` times."""

+    line = f"Hello, {name}!"

+    return "\n".join([line] * times)

 # [/greet]

Line numbers and captions

:linenos:, :lineno-start:, :name: and :class: mean exactly what they do on a .. code-block::, and a :caption: with no value takes the filename:

100def main() -> int:
101    print(greet("world"))
102    return 0

A reference to The entry point resolves to the block above.