Move theme into a python package (pandas-dev#22)

Author: jorisvandenbossche

.travis.yml

@@ -26,6 +26,7 @@ install:
 
 script:
   - set -e
+  - pip install -e .
   - cd pandas-docs
   - python make.py html
   - cd ..

pandas-docs/source/conf.py

@@ -23,9 +23,7 @@
 
 logger = logging.getLogger(__name__)
 
-
-sys.path.append('.')
-from bootstrap_html_translator import BootstrapHTML5Translator
+import pandas_sphinx_theme
 
 
 # -----------------------------------------------------------------------------
@@ -109,144 +107,86 @@ def run(self):
 # -----------------------------------------------------------------------------
 # Sphinx monkeypatch
 
-from sphinx.environment.adapters.toctree import process_only_nodes
-from docutils import nodes
-from sphinx import addnodes
-
-
-def get_toc_for(self, docname, builder):
-    # type: (str, Builder) -> nodes.Node
-    """Return a TOC nodetree -- for use on the same page only!"""
-    tocdepth = self.env.metadata[docname].get('tocdepth', 0)
-    try:
-        toc = self.env.tocs[docname].deepcopy()
-        self._toctree_prune(toc, 2, tocdepth)
-    except KeyError:
-        # the document does not exist anymore: return a dummy node that
-        # renders to nothing
-        return nodes.paragraph()
-    process_only_nodes(toc, builder.tags)
-    for node in toc.traverse(nodes.reference):
-        node['refuri'] = node['anchorname'] or '#'
-
-    # tag toc with attributes
-    toc.attributes['classes'].append('section-nav')
-
-    def tag_childs(bullet_list, level):
-        for sub in bullet_list.children:
-            if getattr(sub, 'tagname', '') == 'list_item':
-                sub.attributes['classes'].extend(['toc-entry', 'toc-h{}'.format(level)])
-                for sub2 in sub.children:
-                    if getattr(sub2, 'tagname', '') == 'bullet_list':
-                        tag_childs(sub2, level + 1)
-
-    tag_childs(toc, 1)
-
-    return toc
-
-def get_toctree_for(self, docname, builder, collapse, **kwds):
-    # type: (str, Builder, bool, Any) -> nodes.Element
-    """Return the global TOC nodetree."""
-    #import pdb; pdb.set_trace()
-    doctree = self.env.get_doctree(self.env.config.master_doc)
-    toctrees = []  # type: List[nodes.Element]
-    if 'includehidden' not in kwds:
-        kwds['includehidden'] = True
-    if 'maxdepth' not in kwds:
-        kwds['maxdepth'] = 0
-    kwds['collapse'] = collapse
-    mindepth = kwds.pop('mindepth', False)
-    for toctreenode in doctree.traverse(addnodes.toctree):
-        toctree = self.resolve(docname, builder, toctreenode, prune=True, **kwds)
-        if toctree:
-            toctrees.append(toctree)
-    if not toctrees:
-        return None
-    result = toctrees[0]
-    for toctree in toctrees[1:]:
-        result.extend(toctree.children)
-    if mindepth and docname not in ('index', 'genindex', 'search'):
-        #import pdb; pdb.set_trace()
-        result = get_current_section_toctree(result)
-    return result
-
-
-def get_current_section_toctree(toctree):
-    actual_toctree = toctree[0]
-    for subtoc in actual_toctree.children:
-        if 'current' in subtoc.attributes['classes']:
-            newtoc = subtoc.children[1]
-            break
-    else:
-        newtoc = actual_toctree
-    toctree[0] = newtoc
-    toctree[0].attributes['classes'].extend(['nav', 'bd-sidenav', 'active'])
-    #import pdb; pdb.set_trace()
-    return toctree
-
-
-import sphinx.environment.adapters.toctree
-sphinx.environment.adapters.toctree.TocTree.get_toc_for = get_toc_for
-sphinx.environment.adapters.toctree.TocTree.get_toctree_for = get_toctree_for
-
-
-def convert_docutils_node(list_item):
-    if not list_item.children:
-        return None
-    reference = list_item.children[0].children[0]
-    title = reference.astext()
-    url = reference.attributes['refuri']
-    active = 'current' in list_item.attributes['classes']
-
-    nav = {}
-    nav['title'] = title
-    nav['url'] = url
-    nav['children'] = []
-    nav['active'] = active
-
-    if len(list_item.children) > 1:
-        for child_item in list_item.children[1].children:
-            child_nav = convert_docutils_node(child_item)
-            if child_nav is not None:
-                nav['children'].append(child_nav)
-
-    return nav
-
-
-def update_page_context(self, pagename, templatename, ctx, event_arg):
-    from sphinx.environment.adapters.toctree import TocTree
-
-    def get_nav_object(**kwds):
-        toctree = TocTree(self.env).get_toctree_for(
-            pagename, self, collapse=True, **kwds)
-
-        nav = []
-        for child in toctree.children[0].children:
-            child_nav = convert_docutils_node(child)
-            nav.append(child_nav)
-
-        return nav
-
-    def get_page_toc_object():
-        self_toc = TocTree(self.env).get_toc_for(pagename, self)
-        toc = self.render_partial(self_toc)['fragment']
-
-        try:
-            #import pdb; pdb.set_trace()
-            nav = convert_docutils_node(self_toc.children[0])
-            #import pdb; pdb.set_trace()
-            return nav
-        except:
-            return {}
-
-    #import pdb; pdb.set_trace()
-    ctx['get_nav_object'] = get_nav_object
-    ctx['get_page_toc_object'] = get_page_toc_object
-    return None
-
+# from sphinx.environment.adapters.toctree import process_only_nodes
+# from docutils import nodes
+# from sphinx import addnodes
+
+
+# def get_toc_for(self, docname, builder):
+#     # type: (str, Builder) -> nodes.Node
+#     """Return a TOC nodetree -- for use on the same page only!"""
+#     tocdepth = self.env.metadata[docname].get('tocdepth', 0)
+#     try:
+#         toc = self.env.tocs[docname].deepcopy()
+#         self._toctree_prune(toc, 2, tocdepth)
+#     except KeyError:
+#         # the document does not exist anymore: return a dummy node that
+#         # renders to nothing
+#         return nodes.paragraph()
+#     process_only_nodes(toc, builder.tags)
+#     for node in toc.traverse(nodes.reference):
+#         node['refuri'] = node['anchorname'] or '#'
+
+#     # tag toc with attributes
+#     toc.attributes['classes'].append('section-nav')
+
+#     def tag_childs(bullet_list, level):
+#         for sub in bullet_list.children:
+#             if getattr(sub, 'tagname', '') == 'list_item':
+#                 sub.attributes['classes'].extend(['toc-entry', 'toc-h{}'.format(level)])
+#                 for sub2 in sub.children:
+#                     if getattr(sub2, 'tagname', '') == 'bullet_list':
+#                         tag_childs(sub2, level + 1)
+
+#     tag_childs(toc, 1)
+
+#     return toc
+
+# def get_toctree_for(self, docname, builder, collapse, **kwds):
+#     # type: (str, Builder, bool, Any) -> nodes.Element
+#     """Return the global TOC nodetree."""
+#     #import pdb; pdb.set_trace()
+#     doctree = self.env.get_doctree(self.env.config.master_doc)
+#     toctrees = []  # type: List[nodes.Element]
+#     if 'includehidden' not in kwds:
+#         kwds['includehidden'] = True
+#     if 'maxdepth' not in kwds:
+#         kwds['maxdepth'] = 0
+#     kwds['collapse'] = collapse
+#     mindepth = kwds.pop('mindepth', False)
+#     for toctreenode in doctree.traverse(addnodes.toctree):
+#         toctree = self.resolve(docname, builder, toctreenode, prune=True, **kwds)
+#         if toctree:
+#             toctrees.append(toctree)
+#     if not toctrees:
+#         return None
+#     result = toctrees[0]
+#     for toctree in toctrees[1:]:
+#         result.extend(toctree.children)
+#     if mindepth and docname not in ('index', 'genindex', 'search'):
+#         #import pdb; pdb.set_trace()
+#         result = get_current_section_toctree(result)
+#     return result
+
+
+# def get_current_section_toctree(toctree):
+#     actual_toctree = toctree[0]
+#     for subtoc in actual_toctree.children:
+#         if 'current' in subtoc.attributes['classes']:
+#             newtoc = subtoc.children[1]
+#             break
+#     else:
+#         newtoc = actual_toctree
+#     toctree[0] = newtoc
+#     toctree[0].attributes['classes'].extend(['nav', 'bd-sidenav', 'active'])
+#     #import pdb; pdb.set_trace()
+#     return toctree
+
+
+# import sphinx.environment.adapters.toctree
+# sphinx.environment.adapters.toctree.TocTree.get_toc_for = get_toc_for
+# sphinx.environment.adapters.toctree.TocTree.get_toctree_for = get_toctree_for
 
-import sphinx.builders.html
-sphinx.builders.html.StandaloneHTMLBuilder.update_page_context = update_page_context
 
 # -----------------------------------------------------------------------------
 
@@ -420,7 +360,7 @@ def get_page_toc_object():
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'bootstrap_docs_theme'
+html_theme = 'pandas_sphinx_theme'
 
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
@@ -433,7 +373,7 @@ def get_page_toc_object():
 # html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = ['_themes']
+#html_theme_path = ['_themes']
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -989,4 +929,3 @@ def setup(app):
     app.add_autodocumenter(AccessorMethodDocumenter)
     app.add_autodocumenter(AccessorCallableDocumenter)
     app.add_directive('autosummary', PandasAutosummary)
-    app.set_translator('html', BootstrapHTML5Translator)

pandas_sphinx_theme/__init__.py

@@ -0,0 +1,87 @@
+"""
+Sphinx Bootstrap theme.
+
+Adapted for the pandas documentation.
+"""
+import os
+
+import sphinx.builders.html
+
+from .bootstrap_html_translator import BootstrapHTML5Translator
+
+
+__version__ = "0.0.1.dev0"
+
+
+# -----------------------------------------------------------------------------
+# Sphinx monkeypatch for adding toctree objects into context
+
+
+def convert_docutils_node(list_item):
+    if not list_item.children:
+        return None
+    reference = list_item.children[0].children[0]
+    title = reference.astext()
+    url = reference.attributes["refuri"]
+    active = "current" in list_item.attributes["classes"]
+
+    nav = {}
+    nav["title"] = title
+    nav["url"] = url
+    nav["children"] = []
+    nav["active"] = active
+
+    if len(list_item.children) > 1:
+        for child_item in list_item.children[1].children:
+            child_nav = convert_docutils_node(child_item)
+            if child_nav is not None:
+                nav["children"].append(child_nav)
+
+    return nav
+
+
+def update_page_context(self, pagename, templatename, ctx, event_arg):
+    from sphinx.environment.adapters.toctree import TocTree
+
+    def get_nav_object(**kwds):
+        toctree = TocTree(self.env).get_toctree_for(
+            pagename, self, collapse=True, **kwds
+        )
+
+        nav = []
+        for child in toctree.children[0].children:
+            child_nav = convert_docutils_node(child)
+            nav.append(child_nav)
+
+        return nav
+
+    def get_page_toc_object():
+        self_toc = TocTree(self.env).get_toc_for(pagename, self)
+
+        try:
+            nav = convert_docutils_node(self_toc.children[0])
+            return nav
+        except:
+            return {}
+
+    ctx["get_nav_object"] = get_nav_object
+    ctx["get_page_toc_object"] = get_page_toc_object
+    return None
+
+
+sphinx.builders.html.StandaloneHTMLBuilder.update_page_context = update_page_context
+
+
+# -----------------------------------------------------------------------------
+
+
+def get_html_theme_path():
+    """Return list of HTML theme paths."""
+    theme_path = os.path.abspath(os.path.dirname(__file__))
+    return [theme_path]
+
+
+def setup(app):
+    theme_path = get_html_theme_path()[0]
+    app.add_html_theme("pandas_sphinx_theme", theme_path)
+    app.set_translator("html", BootstrapHTML5Translator)

pandas-docs/source/bootstrap_html_translator.py renamed to pandas_sphinx_theme/bootstrap_html_translator.py

@@ -34,12 +34,6 @@
       {% endfor %}
     </ul>
 
-<!--
-{# Adding this because our list is not yet with two levels#}
-<div class="bd-toc-item active">
-  {{ toctree(includehidden=theme_sidebar_includehidden, collapse=theme_sidebar_collapse, mindepth=True) }}
-</div>
--->
 </nav>
 
 

pandas-docs/source/_themes/bootstrap_docs_theme/docs-navbar.html renamed to pandas_sphinx_theme/docs-navbar.html

@@ -0,0 +1,27 @@
+"""Sphinx Bootstrap Theme package."""
+from setuptools import setup
+
+from pandas_sphinx_theme import __version__
+
+
+setup(
+    name="pandas-sphinx-theme",
+    version=__version__,
+    description="Sphinx Bootstrap Theme - pandas version.",
+    url="https://github.com/pandas-dev/pandas-sphinx-theme",
+    #
+    packages=["pandas_sphinx_theme"],
+    package_data={
+        "pandas_sphinx_theme": [
+            "theme.conf",
+            "*.html",
+            "static/css/*.css",
+            "static/js/*.js",
+            "static/img/*",
+        ]
+    },
+    include_package_data=True,
+    # See http://www.sphinx-doc.org/en/stable/theming.html#distribute-your-theme-as-a-python-package
+    entry_points={"sphinx.html_themes": ["pandas_sphinx_theme = pandas_sphinx_theme"]},
+    install_requires=["sphinx"],
+)