diff options
-rw-r--r-- | CHANGES | 1 | ||||
-rw-r--r-- | doc/extdev/index.rst | 5 | ||||
-rw-r--r-- | doc/usage/builders/index.rst | 6 | ||||
-rw-r--r-- | setup.py | 1 | ||||
-rw-r--r-- | sphinx/application.py | 2 | ||||
-rw-r--r-- | sphinx/builders/devhelp.py | 132 |
6 files changed, 25 insertions, 122 deletions
@@ -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 diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index fa73681b9..56f2e7cee 100644 --- a/doc/extdev/index.rst +++ b/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 diff --git a/doc/usage/builders/index.rst b/doc/usage/builders/index.rst index d8c3a26c1..3d66604a3 100644 --- a/doc/usage/builders/index.rst +++ b/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 @@ -15,6 +15,7 @@ if sys.version_info < (3, 5): sys.exit(1) install_requires = [ + 'sphinxcontrib-devhelp', 'sphinxcontrib-jsmath', 'sphinxcontrib-qthelp', 'Jinja2>=2.3', diff --git a/sphinx/application.py b/sphinx/application.py index 052426ff7..8565886e6 100644 --- a/sphinx/application.py +++ b/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. 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', |