File Inclusion#


..literalincludes:: is a particular Sphinx reST directive.

..literalincludes:: purpose is to read and render text files into the documentation.

How-to#

Caution

..literalinclude does not use the System Path to connect to target files. The target files location is relative to the calling file.

Often the target file is in the same folder as the calling file, as in this example, see the reST syntax tab for the code.

See the Path Examples tab for more information on how to access target files in different directories.

 1Example file for literal include: file_tree_literal_include_example_1.txt
 2
 3junction-box
 4├── file_tree_literal_include_example_2.txt
 5├── code_examples
 6│   ├── __init__.py
 7│   ├── __pycache__
 8│   │   ├── __init__.cpython-39.pyc
 9│   │   ├── reST_docstrings_example.cpython-39.pyc
10│   │   ├── simple_calculators_example.cpython-39.pyc
11│   │   └── square_example.cpython-39.pyc
12│   ├── reST_docstrings_example.py
13│   ├── simple_calculators_example.py
14│   └── square_example.py
15│
16│
17└── docs
18    └── source
19        ├── _static
20        │   ├── code_examples_2
21        │   │   ├── square_example.py
22        │   │   └── file_tree_literal_include_example_3.txt
23        │   └── css
24        │       └── custom.css
25        └── how-to
26            ├── how-to-docker-linux-cheatsheet.rst
27            ├── index-how-to.rst
28            └── reST
29                ├── file_tree_literal_include_example_1.txt
30                ├── file_tree_literal_include_example_1_old.txt
31                ├── index-reST.rst
32                ├── reST-admonitions.rst
33                ├── reST-inline-tabs.rst
34                ├── reST-intro-rest-sphinx.rst
35                ├── reST-literalinclude-file.rst
36                ├── reST-titles-headings.rst
37                └── reST-toctree.rst

Note

Line 1: Example file name.

Line 26: Location of the file being called.

Line 32: Location of the .. literalinclude:: calling the file.

1.. literalinclude:: file_tree_literal_include_example_1.txt
2:language: text
3:linenos:
4:emphasize-lines: 1, 26, 35

Hint

This example demonstrates ..literalinclude <path-to-file> with the target file three folders above.

1.. literalinclude:: ../../../../file_tree_literal_include_example_2.txt
2 :language: text
3 :linenos:
4 :emphasize-lines: 1, 4, 35

 1Example file for literal include: file_tree_literal_include_example_2.txt
 2
 3junction-box
 4├── file_tree_literal_include_example_2.txt
 5├── code_examples
 6│   ├── __init__.py
 7│   ├── __pycache__
 8│   │   ├── __init__.cpython-39.pyc
 9│   │   ├── reST_docstrings_example.cpython-39.pyc
10│   │   ├── simple_calculators_example.cpython-39.pyc
11│   │   └── square_example.cpython-39.pyc
12│   ├── reST_docstrings_example.py
13│   ├── simple_calculators_example.py
14│   └── square_example.py
15│
16│
17└── docs
18    └── source
19        ├── _static
20        │   ├── code_examples_2
21        │   │   ├── square_example.py
22        │   │   └── file_tree_literal_include_example_3.txt
23        │   └── css
24        │       └── custom.css
25        └── how-to
26            ├── how-to-docker-linux-cheatsheet.rst
27            ├── index-how-to.rst
28            └── reST
29                ├── file_tree_literal_include_example_1.txt
30                ├── file_tree_literal_include_example_1_old.txt
31                ├── index-reST.rst
32                ├── reST-admonitions.rst
33                ├── reST-inline-tabs.rst
34                ├── reST-intro-rest-sphinx.rst
35                ├── reST-literalinclude-file.rst
36                ├── reST-titles-headings.rst
37                └── reST-toctree.rst

Note

Line 1: Example file name.

Line 4: Location of the file being called.

Line 32: Location of the .. literalinclude:: calling the file.

Hint

This example demonstrates ..literalinclude <path-to-file> with the target file up one folder and across two folders.

1.. literalinclude:: ../../_static/code_examples_2/file_tree_literal_include_example_2.txt
2 :language: text
3 :linenos:
4 :emphasize-lines: 1, 22, 35

 1Example file for literal include: file_tree_literal_include_example_3.txt
 2
 3junction-box
 4├── file_tree_literal_include_example_2.txt
 5├── code_examples
 6│   ├── __init__.py
 7│   ├── __pycache__
 8│   │   ├── __init__.cpython-39.pyc
 9│   │   ├── reST_docstrings_example.cpython-39.pyc
10│   │   ├── simple_calculators_example.cpython-39.pyc
11│   │   └── square_example.cpython-39.pyc
12│   ├── reST_docstrings_example.py
13│   ├── simple_calculators_example.py
14│   └── square_example.py
15│
16│
17└── docs
18    └── source
19        ├── _static
20        │   ├── code_examples_2
21        │   │   ├── square_example.py
22        │   │   └── file_tree_literal_include_example_3.txt
23        │   └── css
24        │       └── custom.css
25        └── how-to
26            ├── how-to-docker-linux-cheatsheet.rst
27            ├── index-how-to.rst
28            └── reST
29                ├── file_tree_literal_include_example_1.txt
30                ├── file_tree_literal_include_example_1_old.txt
31                ├── index-reST.rst
32                ├── reST-admonitions.rst
33                ├── reST-inline-tabs.rst
34                ├── reST-intro-rest-sphinx.rst
35                ├── reST-literalinclude-file.rst
36                ├── reST-titles-headings.rst
37                └── reST-toctree.rst

Note

Line 1: Example file name.

Line 22: Location of the file being called.

Line 32: Location of the .. literalinclude:: calling the file.

See Reference section below for modifying options.

Reference#


Examples follow below, in the How it Looks and reST syntax tabs of using optional classes to change the rendered files appearance.

Line Numbers

 1# version: 2
 2
 3build:
 4  image: testing
 5
 6# formats: [pdf]
 7sphinx:
 8  configuration: docs/source/conf.py
 9
10python:
11  version: 3.9
12  install:
13    - method: pip
14      path: .
15      extra_requirements: [doc]

1.. literalinclude:: ../../../../.readthedocs.yaml
2    :language: yaml
3    :linenos:

Line Highlight

 1# version: 2
 2
 3build:
 4  image: testing
 5
 6# formats: [pdf]
 7sphinx:
 8  configuration: docs/source/conf.py
 9
10python:
11  version: 3.9
12  install:
13    - method: pip
14      path: .
15      extra_requirements: [doc]

1.. literalinclude:: ../../../../.readthedocs.yaml
2    :language: yaml
3    :linenos:
4    :emphasize-lines: 1,2, 10-13

Line Selection

1# version: 2
2
3python:
4  version: 3.9
5  install:
6    - method: pip

Tip

Compare this example with the Line Highlight example above.

As seen in the reST syntax tabs, the same lines have been selected and appear here.

Notice that the line numbers in this example are consecutive and don’t indicate the source file line numbers.

1.. literalinclude:: ../../../../.readthedocs.yaml
2    :language: yaml
3    :linenos:
4    :lines: 1,2, 10-13

Code Language


See also

All examples above have used a single yaml file to display the options.

Other code language options exist, and here is a Python file to demonstrate.

For other supported coding languages see Pygments Lexers

 1""" A very very simple square function"""
 2
 3
 4def square(a):
 5    """a very simple squaring function
 6
 7    long description: returns the square of a: :math:`a^2`
 8
 9    :param a: an input argument
10
11    :returns: a*a
12    """
13    return a * a

1.. literalinclude:: ../../_static/code_examples_2/square_example_2.py
2    :language: python
3    :linenos:

File Diff

 1--- /home/docs/checkouts/readthedocs.org/user_builds/junction-box/checkouts/latest/docs/source/how-to/reST/file_tree_literal_include_example_1_old.txt
 2+++ /home/docs/checkouts/readthedocs.org/user_builds/junction-box/checkouts/latest/docs/source/how-to/reST/file_tree_literal_include_example_1.txt
 3@@ -1,15 +1,37 @@
 4-Example file for literal include: File Tree Number 1
 5+Example file for literal include: file_tree_literal_include_example_1.txt
 6 
 7 junction-box
 8 ├── file_tree_literal_include_example_2.txt
 9+├── code_examples
10+│   ├── __init__.py
11+│   ├── __pycache__
12+│   │   ├── __init__.cpython-39.pyc
13+│   │   ├── reST_docstrings_example.cpython-39.pyc
14+│   │   ├── simple_calculators_example.cpython-39.pyc
15+│   │   └── square_example.cpython-39.pyc
16+│   ├── reST_docstrings_example.py
17+│   ├── simple_calculators_example.py
18+│   └── square_example.py
19+│
20+│
21 └── docs
22     └── source
23-        └── reST
24-            ├── index-reST.rst
25-            ├── reST-admonitions.rst
26-            ├── reST-inline-tabs.rst
27-            ├── reST-intro-rest-sphinx.rst
28-            ├── reST-literalinclude-file.rst
29-            ├── reST-titles-headings.rst
30-            ├── reST-toctree.rst
31-            └── file_tree_literal_include_example_1.txt
32+        ├── _static
33+        │   ├── code_examples_2
34+        │   │   ├── square_example.py
35+        │   │   └── file_tree_literal_include_example_3.txt
36+        │   └── css
37+        │       └── custom.css
38+        └── how-to
39+            ├── how-to-docker-linux-cheatsheet.rst
40+            ├── index-how-to.rst
41+            └── reST
42+                ├── file_tree_literal_include_example_1.txt
43+                ├── file_tree_literal_include_example_1_old.txt
44+                ├── index-reST.rst
45+                ├── reST-admonitions.rst
46+                ├── reST-inline-tabs.rst
47+                ├── reST-intro-rest-sphinx.rst
48+                ├── reST-literalinclude-file.rst
49+                ├── reST-titles-headings.rst
50+                └── reST-toctree.rst

1.. literalinclude:: file_tree_literal_include_example_1.txt
2:language: text
3:linenos:
4:diff: file_tree_literal_include_example_1_old.txt

File Encoding

 1# version: 2
 2
 3build:
 4  image: testing
 5
 6# formats: [pdf]
 7sphinx:
 8  configuration: docs/source/conf.py
 9
10python:
11  version: 3.9
12  install:
13    - method: pip
14      path: .
15      extra_requirements: [doc]

Note

Default file encoding is utf-8-sig.

Use this class for different target file encodings, e.g. latin-1.

1.. literalinclude:: ../../../../.readthedocs.yaml
2    :language: yaml
3    :linenos:
4    :encoding: utf-8-sig

Discussion#

The documentation may include more extended text displays by storing the example text in an external plain text file.

Literal include is handy for including code files and has several classes included in the .. code-block:: directive.

It is a more lightweight tool than the Autodoc Sphinx extension to keep small files documentation synchronised with the source file.

Further Reading#


For further interesting reading on this topic, see Spinx Directives.