mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
65 lines
2.4 KiB
ReStructuredText
65 lines
2.4 KiB
ReStructuredText
:mod:`sphinx.ext.viewcode` -- Add links to highlighted source code
|
|
==================================================================
|
|
|
|
.. module:: sphinx.ext.viewcode
|
|
:synopsis: Add links to a highlighted version of the source code.
|
|
.. moduleauthor:: Georg Brandl
|
|
|
|
.. versionadded:: 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 :confval:`viewcode_enable_epub`).
|
|
|
|
There is an additional config value:
|
|
|
|
.. confval:: 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::
|
|
|
|
:confval:`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.
|
|
|
|
.. versionadded:: 1.3
|
|
|
|
.. confval:: 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``.
|
|
|
|
.. versionadded:: 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 <https://github.com/IDPF/epubcheck>`_'s score
|
|
becomes worse even if the reader supports.
|