mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Separate devhelp to sphinxcontrib package
This commit is contained in:
Takeshi KOMIYA
parent
6968889206
commit
2bd69350a7
1
CHANGES
1
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
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
|
||||
1
setup.py
1
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',
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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',
|
||||
|
||||
Loading…
Reference in New Issue
Block a user