: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.
