Linking back to a source code file in Sphinx
Question:
I am documenting a Python module in Sphinx. I have a source code file full of examples of the use of my module. I’d like to reference this file. It is too long to inline as continuous code. Is there a way to create a link to the full source file, formatted in a code-friendly way (i.e: literal or with line numbers)?
Answers:
Python 3 does this. For example, the argparse docs link to the source code (near the top of the page, where it says “Source code”). You can see how they do it by looking at the source for the docs (linked from the first link, down at the bottom of the left had column).
I assume they’re using standard Sphinx, but I am having a hard time finding :source: in their docs…
Update: the :source: role is defined here.
If I get the question right, you want a link from your documentation to the original source file. You can do this by adding the sphinx.ext.viewcode extension to your conf file (under extensions entry). This will create a “source” link for every header of a class, method, function, etc. Clicking the link will open the original file highlighting the clicked item. More explanation here
literalinclude
.. literalinclude:: filename
From the Sphinx (v1.5.1) documentation:
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.
Like code-block, the directive supports the linenos flag option to switch on line numbers, the lineno-start option to select the first line number, the emphasize-lines option to emphasize particular lines, and a language option to select a language different from the current file’s standard language. Example with options:
.. literalinclude:: example.rb
:language: ruby
:emphasize-lines: 12,15-18
:linenos:
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
:encoding: latin-1
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.
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.
Another way to control which part of the file is included is to use the start-after and end-before options (or only one of them). If start-after is given as a string option, only lines that follow the first line containing that string are included. If end-before is given as a string option, only lines that precede the first lines containing that string are included.
When specifying particular parts of a file to display, it can be useful to display exactly which lines are being presented. This can be done using the lineno-match option.
You can prepend and/or append a line to the included code, using the prepend and append option, respectively. This is useful e.g. for highlighting PHP code that doesn’t include the markers.
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
This shows the diff between example.py and example.py.orig with unified diff format.
I am documenting a Python module in Sphinx. I have a source code file full of examples of the use of my module. I’d like to reference this file. It is too long to inline as continuous code. Is there a way to create a link to the full source file, formatted in a code-friendly way (i.e: literal or with line numbers)?
Python 3 does this. For example, the argparse docs link to the source code (near the top of the page, where it says “Source code”). You can see how they do it by looking at the source for the docs (linked from the first link, down at the bottom of the left had column).
I assume they’re using standard Sphinx, but I am having a hard time finding :source: in their docs…
Update: the :source: role is defined here.
If I get the question right, you want a link from your documentation to the original source file. You can do this by adding the sphinx.ext.viewcode extension to your conf file (under extensions entry). This will create a “source” link for every header of a class, method, function, etc. Clicking the link will open the original file highlighting the clicked item. More explanation here
literalinclude
.. literalinclude:: filename
From the Sphinx (v1.5.1) documentation:
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.
Like code-block, the directive supports the linenos flag option to switch on line numbers, the lineno-start option to select the first line number, the emphasize-lines option to emphasize particular lines, and a language option to select a language different from the current file’s standard language. Example with options:
.. literalinclude:: example.rb
:language: ruby
:emphasize-lines: 12,15-18
:linenos:
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
:encoding: latin-1
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.
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.
Another way to control which part of the file is included is to use the start-after and end-before options (or only one of them). If start-after is given as a string option, only lines that follow the first line containing that string are included. If end-before is given as a string option, only lines that precede the first lines containing that string are included.
When specifying particular parts of a file to display, it can be useful to display exactly which lines are being presented. This can be done using the lineno-match option.
You can prepend and/or append a line to the included code, using the prepend and append option, respectively. This is useful e.g. for highlighting PHP code that doesn’t include the markers.
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
This shows the diff between example.py and example.py.orig with unified diff format.