1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
: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.
.. 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 :event:`viewcode-find-source` event.
If :confval:`viewcode_follow_imported_members` is enabled,
you will also need to resolve imported attributes
using the :event:`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 :confval:`viewcode_enable_epub`).
Configuration
-------------
.. confval:: viewcode_follow_imported_members
If this is ``True``, viewcode extension will emit
:event:`viewcode-follow-imported` event to resolve the name of the module
by other extensions. The default is ``True``.
.. versionadded:: 1.3
.. versionchanged:: 1.8
Renamed from ``viewcode_import`` to ``viewcode_follow_imported_members``.
.. 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.
.. event:: viewcode-find-source (app, modname)
.. versionadded:: 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".
:param app: The Sphinx application object.
:param modname: The name of the module to find source code for.
.. event:: viewcode-follow-imported (app, modname, attribute)
.. versionadded:: 1.8
Find the name of the original module for an attribute.
:param app: The Sphinx application object.
:param modname: The name of the module that the attribute belongs to.
:param attribute: The name of the member to follow.
|
