Inital commit

1 files changed, 161 insertions, 0 deletions

diff --git a/sphinx_ascii_theme/__init__.py b/sphinx_ascii_theme/__init__.py
new file mode 100644
index 0000000..160932e
--- /dev/null
+++ b/sphinx_ascii_theme/__init__.py
@@ -0,0 +1,161 @@
+from os import path
+import docutils
+
+"""
+The code of the function add_toctree_functions and docutils_node_to_jinja are
+on the following license:
+
+BSD 3-Clause License
+
+Copyright (c) 2018, pandas
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+It's based on the following project:
+    https://github.com/pandas-dev/pydata-sphinx-theme
+"""
+
+def add_toctree_functions(app, pagename, templatename, context, doctree):
+    """Add functions so Jinja templates can add toctree objects.
+    This converts the docutils nodes into a nested dictionary that Jinja can
+    use in our templating.
+    """
+    from sphinx.environment.adapters.toctree import TocTree
+
+    def get_nav_object(maxdepth=None, collapse=True, **kwargs):
+        """Return a list of nav links that can be accessed from Jinja.
+        Parameters
+        ----------
+        maxdepth: int
+            How many layers of TocTree will be returned
+        collapse: bool
+            Whether to only include sub-pages of the currently-active page,
+            instead of sub-pages of all top-level pages of the site.
+        kwargs: key/val pairs
+            Passed to the `TocTree.get_toctree_for` Sphinx method
+        """
+        # The TocTree will contain the full site TocTree including sub-pages.
+        # "collapse=True" collapses sub-pages of non-active TOC pages.
+        # maxdepth controls how many TOC levels are returned
+        toctree = TocTree(app.env).get_toctree_for(
+            pagename, app.builder, collapse=collapse, maxdepth=maxdepth, **kwargs
+        )
+        # If no toctree is defined (AKA a single-page site), skip this
+        if toctree is None:
+            return []
+
+        # toctree has this structure
+        #   <caption>
+        #   <bullet_list>
+        #       <list_item classes="toctree-l1">
+        #       <list_item classes="toctree-l1">
+        # `list_item`s are the actual TOC links and are the only thing we want
+        toc_items = [
+            item
+            for child in toctree.children
+            for item in child
+            if isinstance(item, docutils.nodes.list_item)
+        ]
+
+        # Now convert our docutils nodes into dicts that Jinja can use
+        nav = [docutils_node_to_jinja(child, only_pages=True) for child in toc_items]
+
+        return nav
+
+    def get_page_toc_object():
+        """Return a list of within-page TOC links that can be accessed from Jinja."""
+        self_toc = TocTree(app.env).get_toc_for(pagename, app.builder)
+
+        try:
+            # If there's only one child, assume we have a single "title" as top header
+            # so start the TOC at the first item's children (AKA, level 2 headers)
+            if len(self_toc.children) == 1:
+                nav = docutils_node_to_jinja(self_toc.children[0]).get("children", [])
+            else:
+                nav = [docutils_node_to_jinja(item) for item in self_toc.children]
+            return nav
+        except Exception:
+            return {}
+
+    context["get_nav_object"] = get_nav_object
+    context["get_page_toc_object"] = get_page_toc_object
+
+
+def docutils_node_to_jinja(list_item, only_pages=False):
+    """Convert a docutils node to a structure that can be read by Jinja.
+    Parameters
+    ----------
+    list_item : docutils list_item node
+        A parent item, potentially with children, corresponding to the level
+        of a TocTree.
+    only_pages : bool
+        Only include items for full pages in the output dictionary. Exclude
+        anchor links (TOC items with a URL that starts with #)
+    Returns
+    -------
+    nav : dict
+        The TocTree, converted into a dictionary with key/values that work
+        within Jinja.
+    """
+    if not list_item.children:
+        return None
+
+    # We assume this structure of a list item:
+    # <list_item>
+    #     <compact_paragraph >
+    #         <reference> <-- the thing we want
+    reference = list_item.children[0].children[0]
+    title = reference.astext()
+    url = reference.attributes["refuri"]
+    active = "current" in list_item.attributes["classes"]
+
+    # If we've got an anchor link, skip it if we wish
+    if only_pages and "#" in url:
+        return None
+
+    # Converting the docutils attributes into jinja-friendly objects
+    nav = {}
+    nav["title"] = title
+    nav["url"] = url
+    nav["active"] = active
+
+    # Recursively convert children as well
+    # If there are sub-pages for this list_item, there should be two children:
+    # a paragraph, and a bullet_list.
+    nav["children"] = []
+    if len(list_item.children) > 1:
+        # The `.children` of the bullet_list has the nodes of the sub-pages.
+        subpage_list = list_item.children[1].children
+        for sub_page in subpage_list:
+            child_nav = docutils_node_to_jinja(sub_page, only_pages=only_pages)
+            if child_nav is not None:
+                nav["children"].append(child_nav)
+    return nav
+
+def setup(app):
+    app.connect("html-page-context", add_toctree_functions)
+    app.add_html_theme('ascii', path.abspath(path.dirname(__file__)))