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

.. _literalinclude:

pre-formatted inclusion 
_________________________

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

   .. literalinclude:: /src/fib.py

This produces:

.. literalinclude:: /src/fib.py

(the root directory which contains the file  :file:`conf.py` also
contains :file:`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:

.. literalinclude:: /src/fib.py
   :linenos:
 
To extract just lines 16, 17 of this file, add the ``:lines:``  role::

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

to get

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

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

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

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