literalinclude

See also

rst:directive:: .. literalinclude:: filename

.. literalinclude:: filename

Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text. The file may be included using the literalinclude directive. For example, to include the Python source file example.py, use:

.. literalinclude:: example.py

The file name is usually relative to the current file’s path. However, if it is absolute (starting with /), it is relative to the top source directory.

Tabs in the input are expanded if you give a tab-width option with the desired tab width.

:linenos:

The directive also supports the linenos flag option to switch on line numbers, and a language option to select a language different from the current file’s standard language. Example with options:

.. literalinclude:: example.rb
   :language: ruby
   :linenos:

:lineno-start:

See also

New in version 1.3: The lineno-start option.

The first line number can be selected with the lineno-start option. If present, linenos is automatically activated as well.

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
"""Returns a table of file names with the following informations

"""

__author__ = "Patrick Vergain <pvergain@gmail.com>"


import hashlib
import logging
import zlib

from unipath import Path


log = logging.getLogger("get_table_hash")


class crc32(object):
    """hashlib-compatible interface for CRC-32 support

    http://stackoverflow.com/questions/1742866/compute-crc-of-file-in-python
    """

    name = "crc32"
    digest_size = 4
    block_size = 1

    def __init__(self, arg=""):
        self.__digest = 0
        self.update(arg)

    def copy(self):
        copy = super(self.__class__, self).__new__(__class__)
        copy.__digest = self.__digest
        return copy

    def digest(self):
        return self.__digest

    def hexdigest(self):
        return "{:08x}".format(self.__digest)

    def update(self, arg):
        self.__digest = zlib.crc32(arg, self.__digest) & 0xFFFFFFFF

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
"""Returns a table of file names with the following informations

"""

__author__ = "Patrick Vergain <pvergain@gmail.com>"


import hashlib
import logging
import zlib

from unipath import Path


log = logging.getLogger("get_table_hash")


class crc32(object):
    """hashlib-compatible interface for CRC-32 support

    http://stackoverflow.com/questions/1742866/compute-crc-of-file-in-python
    """

    name = "crc32"
    digest_size = 4
    block_size = 1

    def __init__(self, arg=""):
        self.__digest = 0
        self.update(arg)

    def copy(self):
        copy = super(self.__class__, self).__new__(__class__)
        copy.__digest = self.__digest
        return copy

    def digest(self):
        return self.__digest

    def hexdigest(self):
        return "{:08x}".format(self.__digest)

    def update(self, arg):
        self.__digest = zlib.crc32(arg, self.__digest) & 0xFFFFFFFF

:diff:

New in version 1.3: The diff option.

If you want to show the diff of the code, you can specify the old file by giving a diff option:

.. literalinclude:: example.py
   :diff: example.py.orig

--- /home/docs/checkouts/readthedocs.org/user_builds/devopstutodoc/checkouts/latest/doc_generators/sphinx/rest_sphinx/code/literalinclude/example.py.orig
+++ /home/docs/checkouts/readthedocs.org/user_builds/devopstutodoc/checkouts/latest/doc_generators/sphinx/rest_sphinx/code/literalinclude/example.py
@@ -1,38 +1,31 @@
-# -*- coding: UTF-8 -*-
-'''Returns a table of file names with the following informations
+"""Returns a table of file names with the following informations
 
-'''
+"""
 
-__author__ = 'Patrick Vergain <pvergain@gmail.com>'
+__author__ = "Patrick Vergain <pvergain@gmail.com>"
 
 
 import hashlib
-
-# see http://petl.readthedocs.org/en/latest/
-# Extract, Transform and Load (Tables of Data)
-from petl import look
-import glob
-import os
-import argparse
 import logging
 import zlib
-import sys
 
 from unipath import Path
 
 
-log = logging.getLogger('get_table_hash')
+log = logging.getLogger("get_table_hash")
+
 
 class crc32(object):
-    '''hashlib-compatible interface for CRC-32 support
+    """hashlib-compatible interface for CRC-32 support
 
     http://stackoverflow.com/questions/1742866/compute-crc-of-file-in-python
-    '''
-    name = 'crc32'
+    """
+
+    name = "crc32"
     digest_size = 4
     block_size = 1
 
-    def __init__(self, arg=''):
+    def __init__(self, arg=""):
         self.__digest = 0
         self.update(arg)
 
@@ -45,7 +38,7 @@
         return self.__digest
 
     def hexdigest(self):
-        return '{:08x}'.format(self.__digest)
+        return "{:08x}".format(self.__digest)
 
     def update(self, arg):
-        self.__digest = zlib.crc32(arg, self.__digest) & 0xffffffff
+        self.__digest = zlib.crc32(arg, self.__digest) & 0xFFFFFFFF

:caption:

New in version 1.3: The caption option.

literalinclude supports the caption option, with the additional feature that if you leave the value empty, the shown filename will be exactly the one given as an argument:

.. literalinclude:: example.py
   :linenos:
   :caption:
example.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
"""Returns a table of file names with the following informations

"""

__author__ = "Patrick Vergain <pvergain@gmail.com>"


import hashlib
import logging
import zlib

from unipath import Path


log = logging.getLogger("get_table_hash")


class crc32(object):
    """hashlib-compatible interface for CRC-32 support

    http://stackoverflow.com/questions/1742866/compute-crc-of-file-in-python
    """

    name = "crc32"
    digest_size = 4
    block_size = 1

    def __init__(self, arg=""):
        self.__digest = 0
        self.update(arg)

    def copy(self):
        copy = super(self.__class__, self).__new__(__class__)
        copy.__digest = self.__digest
        return copy

    def digest(self):
        return self.__digest

    def hexdigest(self):
        return "{:08x}".format(self.__digest)

    def update(self, arg):
        self.__digest = zlib.crc32(arg, self.__digest) & 0xFFFFFFFF

:emphasize-lines:

Additionally, an emphasize-lines option can be given to have Pygments emphasize particular lines:

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

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

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

Changed in version 1.1: emphasize-lines has been added.

:lines: xxx

Alternately, you can specify exactly which lines to include by giving a lines option:

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.

You can combine lines with :emphasize-lines:

:encoding: latin-1

See also

http://sphinx-doc.org/config.html#confval-source_encoding

Include files are assumed to be encoded in the source_encoding. If the file has a different encoding, you can specify it with the encoding option:

.. literalinclude:: example.py
   :language: python
   :encoding: latin-1

:pyobject: xxx

The directive also supports including only parts of the file. If it is a Python module, you can select a class, function or method to include using the pyobject option:

.. literalinclude:: example.py
   :pyobject: Timer.start

This would only include the code lines belonging to the start() method in the Timer class within the file.

:language: python

See also

The valid values for the highlighting language are:

  • none (no highlighting)

  • python (the default when highlight_language isn’t set)

  • guess (let Pygments guess the lexer based on contents, only works with certain well-recognizable languages)

  • rest

  • c

  • … and any other lexer name that Pygments supports.