diff --git a/CHANGES b/CHANGES index 392a2a25e..e53aabdb2 100644 --- a/CHANGES +++ b/CHANGES @@ -62,6 +62,14 @@ Deprecated * ``Sphinx.status_iterator()` and ``Sphinx.old_status_iterator()`` is now deprecated. Please use ``sphinx.util:status_iterator()`` intead. * ``BuildEnvironment.set_warnfunc()`` is now deprecated +* Following methods of ``BuildEnvironment`` is now deprecated. + + - ``BuildEnvironment.note_toctree()`` + - ``BuildEnvironment.get_toc_for()`` + - ``BuildEnvironment.get_toctree_for()`` + - ``BuildEnvironment.create_index()`` + + Please use ``sphinx.environment.adapters`` modules instead. Release 1.5.3 (in development) ============================== diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index f6d21c057..c02e85933 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -359,6 +359,12 @@ package. .. versionadded:: 1.4 +.. method:: Sphinx.add_env_collector(collector) + + Register a environment collector class (refs: :ref:`collector-api`) + + .. versionadded:: 1.6 + .. method:: Sphinx.require_sphinx(version) Compare *version* (which must be a ``major.minor`` version string, diff --git a/doc/extdev/collectorapi.rst b/doc/extdev/collectorapi.rst new file mode 100644 index 000000000..cb4c30bf3 --- /dev/null +++ b/doc/extdev/collectorapi.rst @@ -0,0 +1,9 @@ +.. _collector-api: + +Environment Collector API +------------------------- + +.. module:: sphinx.environment.collectors + +.. autoclass:: EnvironmentCollector + :members: diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index 1f3871c21..85172abb6 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -50,6 +50,7 @@ APIs used for writing extensions appapi envapi builderapi + collectorapi markupapi domainapi parserapi diff --git a/sphinx/application.py b/sphinx/application.py index 839d0101e..d10b89b99 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -55,11 +55,13 @@ if False: from docutils.transform import Transform # NOQA from sphinx.builders import Builder # NOQA from sphinx.domains import Domain, Index # NOQA + from sphinx.environment.collectors import EnvironmentCollector # NOQA # List of all known core events. Maps name to arguments description. events = { 'builder-inited': '', 'env-get-outdated': 'env, added, changed, removed', + 'env-get-updated': 'env', 'env-purge-doc': 'env, docname', 'env-before-read-docs': 'env, docnames', 'source-read': 'docname, source text', @@ -101,6 +103,13 @@ builtin_extensions = ( 'sphinx.directives.other', 'sphinx.directives.patches', 'sphinx.roles', + # collectors should be loaded by specific order + 'sphinx.environment.collectors.dependencies', + 'sphinx.environment.collectors.asset', + 'sphinx.environment.collectors.metadata', + 'sphinx.environment.collectors.title', + 'sphinx.environment.collectors.toctree', + 'sphinx.environment.collectors.indexentries', ) # type: Tuple[unicode, ...] CONFIG_FILENAME = 'conf.py' @@ -300,7 +309,6 @@ class Sphinx(object): logger.info(bold('loading pickled environment... '), nonl=True) self.env = BuildEnvironment.frompickle( self.srcdir, self.config, path.join(self.doctreedir, ENV_PICKLE_FILENAME)) - self.env.init_managers() self.env.domains = {} for domain in self.domains.keys(): # this can raise if the data version doesn't fit @@ -833,6 +841,11 @@ class Sphinx(object): type='app', subtype='add_source_parser') self._additional_source_parsers[suffix] = parser + def add_env_collector(self, collector): + # type: (Type[EnvironmentCollector]) -> None + logger.debug('[app] adding environment collector: %r', collector) + collector().enable(self) + class TemplateBridge(object): """ diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 1461c3e68..dbeca1a34 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -292,7 +292,7 @@ class Builder(object): doccount = len(updated_docnames) logger.info(bold('looking for now-outdated files... '), nonl=1) - for docname in self.env.check_dependents(updated_docnames): + for docname in self.env.check_dependents(self.app, updated_docnames): updated_docnames.add(docname) outdated = len(updated_docnames) - doccount if outdated: diff --git a/sphinx/builders/devhelp.py b/sphinx/builders/devhelp.py index af8bcfeed..031c55184 100644 --- a/sphinx/builders/devhelp.py +++ b/sphinx/builders/devhelp.py @@ -22,6 +22,7 @@ from sphinx import addnodes from sphinx.util import logging from sphinx.util.osutil import make_filename from sphinx.builders.html import StandaloneHTMLBuilder +from sphinx.environment.adapters.indexentries import IndexEntries try: import xml.etree.ElementTree as etree @@ -104,7 +105,7 @@ class DevhelpBuilder(StandaloneHTMLBuilder): # Index functions = etree.SubElement(root, 'functions') - index = self.env.create_index(self) + index = IndexEntries(self.env).create_index(self) def write_index(title, refs, subitems): # type: (unicode, List[Any], Any) -> None diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 3a074a1cc..062c56669 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -45,6 +45,8 @@ from sphinx.highlighting import PygmentsBridge from sphinx.util.console import bold, darkgreen # type: ignore from sphinx.writers.html import HTMLWriter, HTMLTranslator, \ SmartyPantsHTMLTranslator +from sphinx.environment.adapters.toctree import TocTree +from sphinx.environment.adapters.indexentries import IndexEntries if False: # For type annotation @@ -439,7 +441,7 @@ class StandaloneHTMLBuilder(Builder): meta = self.env.metadata.get(docname) # local TOC and global TOC tree - self_toc = self.env.get_toc_for(docname, self) + self_toc = TocTree(self.env).get_toc_for(docname, self) toc = self.render_partial(self_toc)['fragment'] return dict( @@ -541,7 +543,7 @@ class StandaloneHTMLBuilder(Builder): # type: () -> None # the total count of lines for each index letter, used to distribute # the entries into two columns - genindex = self.env.create_index(self) + genindex = IndexEntries(self.env).create_index(self) indexcounts = [] for _k, entries in genindex: indexcounts.append(sum(1 + len(subitems) @@ -763,7 +765,7 @@ class StandaloneHTMLBuilder(Builder): # type: (unicode, bool, Any) -> unicode if 'includehidden' not in kwds: kwds['includehidden'] = False - return self.render_partial(self.env.get_toctree_for( + return self.render_partial(TocTree(self.env).get_toctree_for( docname, self, collapse, **kwds))['fragment'] def get_outfilename(self, pagename): @@ -1010,7 +1012,7 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): # type: (unicode, bool, Any) -> unicode if 'includehidden' not in kwds: kwds['includehidden'] = False - toctree = self.env.get_toctree_for(docname, self, collapse, **kwds) + toctree = TocTree(self.env).get_toctree_for(docname, self, collapse, **kwds) self.fix_refuris(toctree) return self.render_partial(toctree)['fragment'] @@ -1066,7 +1068,8 @@ class SingleFileHTMLBuilder(StandaloneHTMLBuilder): def get_doc_context(self, docname, body, metatags): # type: (unicode, unicode, Dict) -> Dict # no relation links... - toc = self.env.get_toctree_for(self.config.master_doc, self, False) # type: Any + toc = TocTree(self.env).get_toctree_for(self.config.master_doc, + self, False) # if there is no toctree, toc is None if toc: self.fix_refuris(toc) diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py index 08e6f9df4..68fd3b1db 100644 --- a/sphinx/builders/htmlhelp.py +++ b/sphinx/builders/htmlhelp.py @@ -19,6 +19,7 @@ from docutils import nodes from sphinx import addnodes from sphinx.builders.html import StandaloneHTMLBuilder +from sphinx.environment.adapters.indexentries import IndexEntries from sphinx.util import logging from sphinx.util.osutil import make_filename from sphinx.util.pycompat import htmlescape @@ -281,7 +282,7 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): f.write(contents_footer) logger.info('writing index file...') - index = self.env.create_index(self) + index = IndexEntries(self.env).create_index(self) with self.open_file(outdir, outname + '.hhk') as f: f.write('