inclusion

Text in files may be included into the current text either in-line, or pre-formatted.

in-line inclusion

The .. include:: directive causes in-line inclusion:

.. include:: ../../src/some_file.txt

pre-formatted inclusion

to include the file pre-formatted (e.g. quotes or code):

.. literalinclude:: /src/fib.py

This produces:

#!/usr/bin/env python
# -*- encoding: utf-8 -*-
"""Fibonacci sequences using generators

This program is part of "Dive Into Python", a free Python book for
experienced programmers.  Visit http://diveintopython.org/ for the
latest version.
"""

def fibonacci(max):
    a, b = 0, 1
    while a < max:
        yield a
        a, b = b, a+b

for n in fibonacci(1000):
    print n,

(the root directory which contains the file conf.py also contains src, so the file is named absolutely - relative to that directory)

To see that file with line-numbers, add the :linenos: role:

.. literalinclude:: ../../src/fib.py
   :linenos:

which gives:

#!/usr/bin/env python
# -*- encoding: utf-8 -*-
"""Fibonacci sequences using generators

This program is part of "Dive Into Python", a free Python book for
experienced programmers.  Visit http://diveintopython.org/ for the
latest version.
"""

def fibonacci(max):
    a, b = 0, 1
    while a < max:
        yield a
        a, b = b, a+b

for n in fibonacci(1000):
    print n,

To extract just lines 16, 17 of this file, add the :lines: role:

.. literalinclude:: ../../src/fib.py
   :lines: 16-17

to get

for n in fibonacci(1000):
    print n,

We can also include specific functions from python code with the :pyobject: role:

.. literalinclude:: /src/fib.py
   :pyobject: fibonacci

def fibonacci(max):
    a, b = 0, 1
    while a < max:
        yield a
        a, b = b, a+b