Merge pull request #6543 from tk0miya/refactor_indexentries

Proposal: Add IndexDomain for database of general indices

CHANGES

@@ -10,6 +10,8 @@ Incompatible changes
 Deprecated
 ----------
 
+* ``sphinx.environment.BuildEnvironment.indexentries``
+* ``sphinx.environment.collectors.indexentries.IndexEntriesCollector``
 * ``sphinx.io.FiletypeNotFoundError``
 * ``sphinx.io.get_filetype()``
 

doc/extdev/deprecated.rst

@@ -26,6 +26,16 @@ The following is a list of deprecated interfaces.
      - (will be) Removed
      - Alternatives
 
+   * - ``sphinx.environment.BuildEnvironment.indexentries``
+     - 2.4
+     - 4.0
+     - ``sphinx.domains.index.IndexDomain``
+
+   * - ``sphinx.environment.collectors.indexentries.IndexEntriesCollector``
+     - 2.4
+     - 4.0
+     - ``sphinx.domains.index.IndexDomain``
+
    * - ``sphinx.io.FiletypeNotFoundError``
      - 2.4
      - 4.0

sphinx/application.py

@@ -82,6 +82,7 @@ builtin_extensions = (
     'sphinx.domains.changeset',
     'sphinx.domains.citation',
     'sphinx.domains.cpp',
+    'sphinx.domains.index',
     'sphinx.domains.javascript',
     'sphinx.domains.math',
     'sphinx.domains.python',
@@ -111,7 +112,6 @@ builtin_extensions = (
     'sphinx.environment.collectors.metadata',
     'sphinx.environment.collectors.title',
     'sphinx.environment.collectors.toctree',
-    'sphinx.environment.collectors.indexentries',
     # 1st party extensions
     'sphinxcontrib.applehelp',
     'sphinxcontrib.devhelp',

sphinx/domains/index.py

@@ -0,0 +1,65 @@
+"""
+    sphinx.domains.index
+    ~~~~~~~~~~~~~~~~~~~~
+
+    The index domain.
+
+    :copyright: Copyright 2007-2019 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from typing import Any, Dict, Iterable, List, Tuple
+
+from docutils.nodes import Node
+
+from sphinx import addnodes
+from sphinx.application import Sphinx
+from sphinx.domains import Domain
+from sphinx.environment import BuildEnvironment
+from sphinx.util import logging
+from sphinx.util import split_index_msg
+
+
+logger = logging.getLogger(__name__)
+
+
+class IndexDomain(Domain):
+    """Mathematics domain."""
+    name = 'index'
+    label = 'index'
+
+    @property
+    def entries(self) -> Dict[str, List[Tuple[str, str, str, str, str]]]:
+        return self.data.setdefault('entries', {})
+
+    def clear_doc(self, docname: str) -> None:
+        self.entries.pop(docname, None)
+
+    def merge_domaindata(self, docnames: Iterable[str], otherdata: Dict) -> None:
+        for docname in docnames:
+            self.entries[docname] = otherdata['entries'][docname]
+
+    def process_doc(self, env: BuildEnvironment, docname: str, document: Node) -> None:
+        """Process a document after it is read by the environment."""
+        entries = self.entries.setdefault(env.docname, [])
+        for node in document.traverse(addnodes.index):
+            try:
+                for entry in node['entries']:
+                    split_index_msg(entry[0], entry[1])
+            except ValueError as exc:
+                logger.warning(str(exc), location=node)
+                node.parent.remove(node)
+            else:
+                for entry in node['entries']:
+                    entries.append(entry)
+
+
+def setup(app: Sphinx) -> Dict[str, Any]:
+    app.add_domain(IndexDomain)
+
+    return {
+        'version': 'builtin',
+        'env_version': 1,
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }

sphinx/environment/__init__.py

@@ -16,6 +16,7 @@ from copy import copy
 from io import BytesIO
 from os import path
 from typing import Any, Callable, Dict, Generator, IO, Iterator, List, Set, Tuple, Union
+from typing import cast
 
 from docutils import nodes
 from docutils.nodes import Node
@@ -43,6 +44,7 @@ if False:
     from sphinx.application import Sphinx
     from sphinx.builders import Builder
 
+
 logger = logging.getLogger(__name__)
 
 default_settings = {
@@ -169,11 +171,6 @@ class BuildEnvironment:
         self.domaindata = {}        # type: Dict[str, Dict]
                                     # domainname -> domain-specific dict
 
-        # Other inventories
-        self.indexentries = {}      # type: Dict[str, List[Tuple[str, str, str, str, str]]]
-                                    # docname -> list of
-                                    # (type, str, target, aliasname)
-
         # these map absolute path -> (docnames, unique filename)
         self.images = FilenameUniqDict()    # type: FilenameUniqDict
         self.dlfiles = DownloadFiles()      # type: DownloadFiles
@@ -750,6 +747,14 @@ class BuildEnvironment:
         node.line = lineno
         self.get_domain('changeset').note_changeset(node)  # type: ignore
 
+    @property
+    def indexentries(self) -> Dict[str, List[Tuple[str, str, str, str, str]]]:
+        warnings.warn('env.indexentries() is deprecated. Please use IndexDomain instead.',
+                      RemovedInSphinx40Warning)
+        from sphinx.domains.index import IndexDomain
+        domain = cast(IndexDomain, self.get_domain('index'))
+        return domain.entries
+
 
 from sphinx.errors import NoUri  # NOQA
 

sphinx/environment/collectors/indexentries.py

@@ -8,22 +8,29 @@
     :license: BSD, see LICENSE for details.
 """
 
+import warnings
 from typing import Any, Dict, Set
 
 from docutils import nodes
 
 from sphinx import addnodes
 from sphinx.application import Sphinx
+from sphinx.deprecation import RemovedInSphinx40Warning
 from sphinx.environment import BuildEnvironment
 from sphinx.environment.collectors import EnvironmentCollector
 from sphinx.util import split_index_msg, logging
 
+
 logger = logging.getLogger(__name__)
 
 
 class IndexEntriesCollector(EnvironmentCollector):
     name = 'indices'
 
+    def __init__(self) -> None:
+        warnings.warn('IndexEntriesCollector is deprecated.',
+                      RemovedInSphinx40Warning)
+
     def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.indexentries.pop(docname, None)
 

tests/test_build_html.py

@@ -28,9 +28,9 @@ ENV_WARNINGS = """\
 WARNING: Explicit markup ends without a blank line; unexpected unindent.
 %(root)s/index.rst:\\d+: WARNING: Encoding 'utf-8-sig' used for reading included \
 file '%(root)s/wrongenc.inc' seems to be wrong, try giving an :encoding: option
+%(root)s/index.rst:\\d+: WARNING: invalid single index entry ''
 %(root)s/index.rst:\\d+: WARNING: image file not readable: foo.png
 %(root)s/index.rst:\\d+: WARNING: download file not readable: %(root)s/nonexisting.png
-%(root)s/index.rst:\\d+: WARNING: invalid single index entry ''
 %(root)s/undecodable.rst:\\d+: WARNING: undecodable source characters, replacing \
 with "\\?": b?'here: >>>(\\\\|/)xbb<<<((\\\\|/)r)?'
 """