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

Warning:

  Basically, "viewcode" extension will import the modules being linked
  to. If any modules have side effects on import, these will be
  executed 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.In addition, if
  you don't want to import the modules by "viewcode", you can tell the
  location of the location of source code to "viewcode" using the
  "viewcode-find-source" event.If "viewcode_follow_imported_members"
  is enabled, you will also need to resolve imported attributes using
  the "viewcode-follow-imported" event.

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").


Configuration
=============

viewcode_follow_imported_members

   If this is "True", viewcode extension will emit "viewcode-follow-
   imported" event to resolve the name of the module by other
   extensions.  The default is "True".

   New in version 1.3.

   Changed in version 1.8: Renamed from "viewcode_import" to
   "viewcode_follow_imported_members".

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.

viewcode-find-source(app, modname)

   New in version 1.8.

   Find the source code for a module. An event handler for this event
   should return a tuple of the source code itself and a dictionary of
   tags. The dictionary maps the name of a class, function, attribute,
   etc to a tuple of its type, the start line number, and the end line
   number. The type should be one of "class", "def", or "other".

   Parameters:
      * **app** -- The Sphinx application object.

      * **modname** -- The name of the module to find source code for.

viewcode-follow-imported(app, modname, attribute)

   New in version 1.8.

   Find the name of the original module for an attribute.

   Parameters:
      * **app** -- The Sphinx application object.

      * **modname** -- The name of the module that the attribute
        belongs to.

      * **attribute** -- The name of the member to follow.
