Separate devhelp to sphinxcontrib package

1 files changed, 12 insertions, 120 deletions

diff --git a/sphinx/builders/devhelp.py b/sphinx/builders/devhelp.py
index f0948f124..2306ddee2 100644
--- a/sphinx/builders/devhelp.py
+++ b/sphinx/builders/devhelp.py
@@ -10,139 +10,31 @@
     :license: BSD, see LICENSE for details.
 """
 
-import gzip
-import re
-from os import path
-from typing import Any
+import warnings
 
-from docutils import nodes
+from sphinxcontrib.devhelp import DevhelpBuilder
 
-from sphinx import addnodes
-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
+from sphinx.deprecation import RemovedInSphinx40Warning, deprecated_alias
 
-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__)
-
-
-class DevhelpBuilder(StandaloneHTMLBuilder):
-    """
-    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')
+deprecated_alias('sphinx.builders.devhelp',
+                 {
+                     'DevhelpBuilder': DevhelpBuilder,
+                 },
+                 RemovedInSphinx40Warning)
 
 
 def setup(app):
     # type: (Sphinx) -> Dict[str, Any]
-    app.setup_extension('sphinx.builders.html')
-    app.add_builder(DevhelpBuilder)
-
-    app.add_config_value('devhelp_basename', lambda self: make_filename(self.project), None)
+    warnings.warn('sphinx.builders.devhelp has been moved to sphinxcontrib-devhelp.',
+                  RemovedInSphinx40Warning)
+    app.setup_extension('sphinxcontrib.devhelp')
 
     return {
         'version': 'builtin',