Merge pull request #2791 from shibukawa/feature/epub/disablesourcefilepage

Turn off viewcode extension for epub by default

CHANGES

@@ -31,13 +31,14 @@ Incompatible changes
 * QtHelpBuilder uses ``nonav`` theme instead of default one
   to improve readability.
 * latex: To provide good default settings to Japanese docs, Sphinx uses ``jsbooks``
-  as a docclass by default if the `language` is ``ja``.
+  as a docclass by default if the ``language`` is ``ja``.
 * latex: To provide good default settings to Japanese docs, Sphinx uses
   ``jreport`` and ``jsbooks`` as a docclass by default if the ``language`` is
   ``ja``.
-* `sphinx-quickstart` now allows a project version is empty
+* ``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

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 <https://github.com/IDPF/epubcheck>`_'s score
+      becomes worse even if the reader supports.

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)