Separate devhelp to sphinxcontrib package

CHANGES

@@ -21,6 +21,7 @@ Dependencies
 * The sphinxcontrib-websupport package is no longer a dependency
 * Some packages are separated to sub packages:
 
+  - sphinxcontrib.devhelp
   - sphinxcontrib.jsmath
   - sphinxcontrib.qthelp
 

doc/extdev/index.rst

@@ -275,6 +275,11 @@ The following is a list of deprecated interfaces.
      - 4.0
      - ``docutils.nodes.abbreviation``
 
+   * - ``sphinx.builders.devhelp``
+     - 2.0
+     - 4.0
+     - ``sphinxcontrib.devhelp``
+
    * - ``sphinx.builders.epub3.Epub3Builder.validate_config_value()``
      - 2.0
      - 4.0

doc/usage/builders/index.rst

@@ -117,7 +117,7 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. versionadded:: 1.3
 
-.. module:: sphinx.builders.devhelp
+.. module:: sphinxcontrib.devhelp
 .. class:: DevhelpBuilder
 
    This builder produces the same output as the standalone HTML builder, but
@@ -130,6 +130,10 @@ The builder's "name" must be given to the **-b** command-line option of
 
    .. autoattribute:: supported_image_types
 
+   .. versionchanged:: 2.0
+
+      Moved to sphinxcontrib.devhelp from sphinx.builders package.
+
 .. module:: sphinx.builders.epub3
 .. class:: Epub3Builder
 

setup.py

@@ -15,6 +15,7 @@ if sys.version_info < (3, 5):
     sys.exit(1)
 
 install_requires = [
+    'sphinxcontrib-devhelp',
     'sphinxcontrib-jsmath',
     'sphinxcontrib-qthelp',
     'Jinja2>=2.3',

sphinx/application.py

@@ -65,7 +65,6 @@ builtin_extensions = (
     'sphinx.builders.applehelp',
     'sphinx.builders.changes',
     'sphinx.builders.epub3',
-    'sphinx.builders.devhelp',
     'sphinx.builders.dummy',
     'sphinx.builders.gettext',
     'sphinx.builders.html',
@@ -107,6 +106,7 @@ builtin_extensions = (
     'sphinx.environment.collectors.toctree',
     'sphinx.environment.collectors.indexentries',
     # 1st party extensions
+    'sphinxcontrib.devhelp',
     'sphinxcontrib.qthelp',
     # Strictly, alabaster theme is not a builtin extension,
     # but it is loaded automatically to use it as default theme.

sphinx/builders/devhelp.py

@@ -10,139 +10,31 @@
     :license: BSD, see LICENSE for details.
 """
 
-import gzip
+import warnings
-import re
-from os import path
-from typing import Any
 
-from docutils import nodes
+from sphinxcontrib.devhelp import DevhelpBuilder
 
-from sphinx import addnodes
+from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
-from sphinx.builders.html import StandaloneHTMLBuilder
-from sphinx.environment.adapters.indexentries import IndexEntries
-from sphinx.locale import __
-from sphinx.util import logging
-from sphinx.util.nodes import NodeMatcher
-from sphinx.util.osutil import make_filename
 
-try:
-    import xml.etree.ElementTree as etree
-except ImportError:
-    import lxml.etree as etree  # type: ignore
 
 if False:
     # For type annotation
-    from typing import Dict, List  # NOQA
+    from typing import Any, Dict  # NOQA
     from sphinx.application import Sphinx  # NOQA
 
 
-logger = logging.getLogger(__name__)
+deprecated_alias('sphinx.builders.devhelp',
-
+                 {
-
+                     'DevhelpBuilder': DevhelpBuilder,
-class DevhelpBuilder(StandaloneHTMLBuilder):
+                 },
-    """
+                 RemovedInSphinx40Warning)
-    Builder that also outputs GNOME Devhelp file.
-    """
-    name = 'devhelp'
-    epilog = __('To view the help file:\n'
-                '$ mkdir -p $HOME/.local/share/devhelp/books\n'
-                '$ ln -s $PWD/%(outdir)s $HOME/.local/share/devhelp/books/%(project)s\n'
-                '$ devhelp')
-
-    # don't copy the reST source
-    copysource = False
-    supported_image_types = ['image/png', 'image/gif', 'image/jpeg']
-
-    # don't add links
-    add_permalinks = False
-    # don't add sidebar etc.
-    embedded = True
-
-    def init(self):
-        # type: () -> None
-        super().init()
-        self.out_suffix = '.html'
-        self.link_suffix = '.html'
-
-    def handle_finish(self):
-        # type: () -> None
-        self.build_devhelp(self.outdir, self.config.devhelp_basename)
-
-    def build_devhelp(self, outdir, outname):
-        # type: (str, str) -> None
-        logger.info(__('dumping devhelp index...'))
-
-        # Basic info
-        root = etree.Element('book',
-                             title=self.config.html_title,
-                             name=self.config.project,
-                             link="index.html",
-                             version=self.config.version)
-        tree = etree.ElementTree(root)
-
-        # TOC
-        chapters = etree.SubElement(root, 'chapters')
-
-        tocdoc = self.env.get_and_resolve_doctree(
-            self.config.master_doc, self, prune_toctrees=False)
-
-        def write_toc(node, parent):
-            # type: (nodes.Node, etree.Element) -> None
-            if isinstance(node, addnodes.compact_paragraph) or \
-               isinstance(node, nodes.bullet_list):
-                for subnode in node:
-                    write_toc(subnode, parent)
-            elif isinstance(node, nodes.list_item):
-                item = etree.SubElement(parent, 'sub')
-                for subnode in node:
-                    write_toc(subnode, item)
-            elif isinstance(node, nodes.reference):
-                parent.attrib['link'] = node['refuri']
-                parent.attrib['name'] = node.astext()
-
-        matcher = NodeMatcher(addnodes.compact_paragraph, toctree=Any)
-        for node in tocdoc.traverse(matcher):  # type: addnodes.compact_paragraph
-            write_toc(node, chapters)
-
-        # Index
-        functions = etree.SubElement(root, 'functions')
-        index = IndexEntries(self.env).create_index(self)
-
-        def write_index(title, refs, subitems):
-            # type: (str, List[Any], Any) -> None
-            if len(refs) == 0:
-                pass
-            elif len(refs) == 1:
-                etree.SubElement(functions, 'function',
-                                 name=title, link=refs[0][1])
-            else:
-                for i, ref in enumerate(refs):
-                    etree.SubElement(functions, 'function',
-                                     name="[%d] %s" % (i, title),
-                                     link=ref[1])
-
-            if subitems:
-                parent_title = re.sub(r'\s*\(.*\)\s*$', '', title)
-                for subitem in subitems:
-                    write_index("%s %s" % (parent_title, subitem[0]),
-                                subitem[1], [])
-
-        for (key, group) in index:
-            for title, (refs, subitems, key) in group:
-                write_index(title, refs, subitems)
-
-        # Dump the XML file
-        xmlfile = path.join(outdir, outname + '.devhelp.gz')
-        with gzip.open(xmlfile, 'w') as f:
-            tree.write(f, 'utf-8')
 
 
 def setup(app):
     # type: (Sphinx) -> Dict[str, Any]
-    app.setup_extension('sphinx.builders.html')
+    warnings.warn('sphinx.builders.devhelp has been moved to sphinxcontrib-devhelp.',
-    app.add_builder(DevhelpBuilder)
+                  RemovedInSphinx40Warning)
-
+    app.setup_extension('sphinxcontrib.devhelp')
-    app.add_config_value('devhelp_basename', lambda self: make_filename(self.project), None)
 
     return {
         'version': 'builtin',