Showing Source Code

Using a code block

Show a Python code block with highlighted lines:

.. code-block:: python
   :linenos:
   :emphasize-lines: 3,5

   def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one is not...'
       print '...but this one is.'

And this is how it looks like:

1
2
3
4
5
def some_function():
    interesting = False
    print 'This line is highlighted.'
    print 'This one is not...'
    print '...but this one is.'

Include Source Code

Include source code from a file and show only a part of it:

.. literalinclude:: ../../giza/__init__.py
   :language: python
   :linenos:
   :lines: 11-26

And here is how it looks like:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
def calc_square(number, verbosity):
    """
    Calculate the square of a given number.

    :param number: An integer number.
    :param verbosity: An integer value for output verbosity.
    :return: The square of number.
    """
    answer = number**2
    if verbosity >= 2:
        print "the square of {} equals {}".format(number, answer)
    elif verbosity >= 1:
        print "{}^2 == {}".format(number, answer)
    else:
        print answer
    return answer

Use Sphinx autoapi

sphinx-autoapi is a tool to make API docs. It depends on parsing, instead of importing code.

First you need to install autoapi:

$ pip install sphinx-autoapi

Then add it to your Sphinx project’s conf.py:

extensions = ['autoapi.extension']

# Document Python Code
autoapi_type = 'python'
autoapi_dir = '../src'

AutoAPI will automatically add itself to the last TOCTree in your top-level index.rst.

This is needed because we will be outputting rst files into the autoapi directory. This adds it into the global TOCTree for your project, so that it appears in the menus.

Note

Life Preview of Giza autoapi