diff --git a/CHANGES b/CHANGES index 95b65a194..8782e43d2 100644 --- a/CHANGES +++ b/CHANGES @@ -37,7 +37,8 @@ Incompatible changes ``ja``. * `sphinx-quickstart` now allows a project version is empty * Fix :download: role on epub/qthelp builder. They ignore the role because they don't support it. - +* ``sphinx.ext.viewcode`` doesn't work on epub building by default. ``viewcode_enable_epub`` option +* ``sphinx.ext.viewcode`` disabled on singlehtml builder. Features added -------------- @@ -66,6 +67,7 @@ Features added - two lengths ``\sphinxverbatimsep`` and ``\sphinxverbatimborder``, - booleans ``\ifsphinxverbatimwithframe`` and ``\ifsphinxverbatimwrapslines``. + * latex, captions for literal blocks inside tables are handled, and long code lines wrapped to fit table cell (ref: #2704) * #2597: Show warning messages as darkred diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst index 5bf8eb033..5823090f6 100644 --- a/doc/ext/viewcode.rst +++ b/doc/ext/viewcode.rst @@ -15,6 +15,11 @@ 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 @@ -34,3 +39,26 @@ There is an additional config value: 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 `_'s score + becomes worse even if the reader supports. diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py index a071c5533..276a137d5 100644 --- a/sphinx/ext/viewcode.py +++ b/sphinx/ext/viewcode.py @@ -46,6 +46,10 @@ def doctree_read(app, doctree): env = app.builder.env if not hasattr(env, '_viewcode_modules'): env._viewcode_modules = {} + if app.builder.name == "singlehtml": + return + if app.builder.name.startswith("epub") and not env.config.viewcode_enable_epub: + return def has_tag(modname, fullname, docname, refname): entry = env._viewcode_modules.get(modname, None) @@ -215,6 +219,7 @@ def collect_pages(app): def setup(app): app.add_config_value('viewcode_import', True, False) + app.add_config_value('viewcode_enable_epub', False, False) app.connect('doctree-read', doctree_read) app.connect('env-merge-info', env_merge_info) app.connect('html-collect-pages', collect_pages)