sphinx.ext.viewcode – Add links to highlighted source code

Module author: Georg Brandl

New in version 1.0.

This extension looks at your Python object descriptions (.. class::, .. function:: etc.) and tries to find the source files where the objects are contained. When found, a separate HTML page will be output for each module with a highlighted version of the source code, and a link will be added to all object descriptions that leads to the source code of the described object. A link back from the source to the description will also be inserted.

This extension works only on HTML related builders like html, applehelp, devhelp, htmlhelp, qthelp and so on except singlehtml. By default epub builder doesn’t support this extension (see viewcode_enable_epub).

There is an additional config value:

viewcode_import

If this is True, viewcode extension will follow alias objects that imported from another module such as functions, classes and attributes. As side effects, this option else they produce nothing. The default is True.

Warning

viewcode_import imports the modules to be followed real location. If any modules have side effects on import, these will be executed by viewcode when sphinx-build is run.

If you document scripts (as opposed to library modules), make sure their main routine is protected by a if __name__ == '__main__' condition.

New in version 1.3.

viewcode_enable_epub

If this is True, viewcode extension is also enabled even if you use epub builders. This extension generates pages outside toctree, but this is not preferred as epub format.

Until 1.4.x, this extension is always enabled. If you want to generate epub as same as 1.4.x, you should set True, but epub format checker’s score becomes worse.

The default is False.

New in version 1.5.

Warning

Not all epub readers support pages generated by viewcode extension. These readers ignore links to pages are not under toctree.

Some reader’s rendering result are corrupted and epubcheck‘s score becomes worse even if the reader supports.