- squash-merge the improve_toc branch, which moves all the Sphinx styling

and extensions into an external library, and also reorganizes most large documentation
pages into many small areas to reduce scrolling and better present the context
into a more fine-grained hierarchy.

1 files changed, 0 insertions, 209 deletions

diff --git a/doc/build/builder/viewsource.py b/doc/build/builder/viewsource.py
deleted file mode 100644
index 088cef2c2..000000000
--- a/doc/build/builder/viewsource.py
+++ /dev/null
@@ -1,209 +0,0 @@
-from docutils import nodes
-from sphinx.ext.viewcode import collect_pages
-from sphinx.pycode import ModuleAnalyzer
-import imp
-from sphinx import addnodes
-import re
-from sphinx.util.compat import Directive
-import os
-from docutils.statemachine import StringList
-from sphinx.environment import NoUri
-
-import sys
-
-py2k = sys.version_info < (3, 0)
-if py2k:
-    text_type = unicode
-else:
-    text_type = str
-
-def view_source(name, rawtext, text, lineno, inliner,
-                      options={}, content=[]):
-
-    env = inliner.document.settings.env
-
-    node = _view_source_node(env, text, None)
-    return [node], []
-
-def _view_source_node(env, text, state):
-    # pretend we're using viewcode fully,
-    # install the context it looks for
-    if not hasattr(env, '_viewcode_modules'):
-        env._viewcode_modules = {}
-
-    modname = text
-    text = modname.split(".")[-1] + ".py"
-
-    # imitate sphinx .<modname> syntax
-    if modname.startswith("."):
-        # see if the modname needs to be corrected in terms
-        # of current module context
-        base_module = env.temp_data.get('autodoc:module')
-        if base_module is None:
-            base_module = env.temp_data.get('py:module')
-
-        if base_module:
-            modname = base_module + modname
-
-    urito = env.app.builder.get_relative_uri
-
-    # we're showing code examples which may have dependencies
-    # which we really don't want to have required so load the
-    # module by file, not import (though we are importing)
-    # the top level module here...
-    pathname = None
-    for token in modname.split("."):
-        file_, pathname, desc = imp.find_module(token, [pathname] if pathname else None)
-        if file_:
-            file_.close()
-
-    # unlike viewcode which silently traps exceptions,
-    # I want this to totally barf if the file can't be loaded.
-    # a failed build better than a complete build missing
-    # key content
-    analyzer = ModuleAnalyzer.for_file(pathname, modname)
-    # copied from viewcode
-    analyzer.find_tags()
-    if not isinstance(analyzer.code, text_type):
-        code = analyzer.code.decode(analyzer.encoding)
-    else:
-        code = analyzer.code
-
-    if state is not None:
-        docstring = _find_mod_docstring(analyzer)
-        if docstring:
-            # get rid of "foo.py" at the top
-            docstring = re.sub(r"^[a-zA-Z_0-9]+\.py", "", docstring)
-
-            # strip
-            docstring = docstring.strip()
-
-            # yank only first paragraph
-            docstring = docstring.split("\n\n")[0].strip()
-    else:
-        docstring = None
-
-    entry = code, analyzer.tags, {}
-    env._viewcode_modules[modname] = entry
-    pagename = '_modules/' + modname.replace('.', '/')
-
-    try:
-        refuri = urito(env.docname, pagename)
-    except NoUri:
-        # if we're in the latex builder etc., this seems
-        # to be what we get
-        refuri = None
-
-
-    if docstring:
-        # embed the ref with the doc text so that it isn't
-        # a separate paragraph
-        if refuri:
-            docstring = "`%s <%s>`_ - %s" % (text, refuri, docstring)
-        else:
-            docstring = "``%s`` - %s" % (text, docstring)
-        para = nodes.paragraph('', '')
-        state.nested_parse(StringList([docstring]), 0, para)
-        return_node = para
-    else:
-        if refuri:
-            refnode = nodes.reference('', '',
-                    nodes.Text(text, text),
-                    refuri=urito(env.docname, pagename)
-                )
-        else:
-            refnode = nodes.Text(text, text)
-
-        if state:
-            return_node = nodes.paragraph('', '', refnode)
-        else:
-            return_node = refnode
-
-    return return_node
-
-from sphinx.pycode.pgen2 import token
-
-def _find_mod_docstring(analyzer):
-    """attempt to locate the module-level docstring.
-
-    Note that sphinx autodoc just uses ``__doc__``.  But we don't want
-    to import the module, so we need to parse for it.
-
-    """
-    analyzer.tokenize()
-    for type_, parsed_line, start_pos, end_pos, raw_line in analyzer.tokens:
-        if type_ == token.COMMENT:
-            continue
-        elif type_ == token.STRING:
-            return eval(parsed_line)
-        else:
-            return None
-
-def _parse_content(content):
-    d = {}
-    d['text'] = []
-    idx = 0
-    for line in content:
-        idx += 1
-        m = re.match(r' *\:(.+?)\:(?: +(.+))?', line)
-        if m:
-            attrname, value = m.group(1, 2)
-            d[attrname] = value or ''
-        else:
-            break
-    d["text"] = content[idx:]
-    return d
-
-def _comma_list(text):
-    return re.split(r"\s*,\s*", text.strip())
-
-class AutoSourceDirective(Directive):
-    has_content = True
-
-    def run(self):
-        content = _parse_content(self.content)
-
-
-        env = self.state.document.settings.env
-        self.docname = env.docname
-
-        sourcefile = self.state.document.current_source.split(os.pathsep)[0]
-        dir_ = os.path.dirname(sourcefile)
-        files = [
-            f for f in os.listdir(dir_) if f.endswith(".py")
-            and f != "__init__.py"
-        ]
-
-        if "files" in content:
-            # ordered listing of files to include
-            files = [fname for fname in _comma_list(content["files"])
-                        if fname in set(files)]
-
-        node = nodes.paragraph('', '',
-                        nodes.Text("Listing of files:", "Listing of files:")
-                )
-
-        bullets = nodes.bullet_list()
-        for fname in files:
-            modname, ext = os.path.splitext(fname)
-            # relative lookup
-            modname = "." + modname
-
-            link = _view_source_node(env, modname, self.state)
-
-            list_node = nodes.list_item('',
-                link
-            )
-            bullets += list_node
-
-        node += bullets
-
-        return [node]
-
-def setup(app):
-    app.add_role('viewsource', view_source)
-
-    app.add_directive('autosource', AutoSourceDirective)
-
-    # from sphinx.ext.viewcode
-    app.connect('html-collect-pages', collect_pages)