Documentation test

docs/_ext/nav.py

@@ -0,0 +1,73 @@
+# -*- coding: utf-8 -*-
+
+from functools import partial
+
+from docutils import nodes
+from sphinx import addnodes
+from sphinx.builders.html import StandaloneHTMLBuilder
+
+
+MAXDEPTH_DEFAULT = 2
+
+
+def patch_builder(app):
+    if isinstance(app.builder, StandaloneHTMLBuilder):
+        app.builder._get_local_toctree = partial(get_local_toctree, app.builder)
+
+
+def get_local_toctree(self, docname, collapse=True, **kwds):
+    """
+    A patched version of `StandaloneHTMLBuilder._get_local_toctree`
+    that calls the modified `get_toctree_for` function.
+    """
+    kwds.setdefault('includehidden', False)
+    toctree = get_toctree_for(self.env, docname, self, collapse, **kwds)
+    return self.render_partial(toctree)['fragment']
+
+
+def get_toctree_for(env, docname, builder, collapse, **kwds):
+    """
+    A wrapper for `environment.get_toctree_for` that shifts the resultant toctree up one level.
+    """
+    toctree = env.get_toctree_for(docname, builder, False, **kwds)
+    newtree = addnodes.compact_paragraph()
+    newtree['toctree'] = True
+
+    maxdepth = env.config.nav_maxdepth
+    try:
+        maxdepth.setdefault('default', MAXDEPTH_DEFAULT)
+    except AttributeError:
+        maxdepth = {'default': maxdepth}
+
+    for top_level_list in toctree:
+        assert isinstance(top_level_list, nodes.bullet_list)
+        for top_level_item in top_level_list.children:
+            assert len(top_level_item) == 2
+            title_node = top_level_item[0][0][0] # compact_paragraph -> reference -> Text
+            list_node = top_level_item[1]
+            env._toctree_prune(node     = list_node,
+                               depth    = 2,
+                               maxdepth = maxdepth.get(title_node.astext(), maxdepth['default']),
+                               collapse = collapse)
+            newtree += nodes.caption(title_node.astext(), '', title_node)
+            newtree += list_node
+    toctree_update_classes(newtree)
+    return newtree
+
+
+def toctree_update_classes(toctree, depth=1):
+    """Update 'toctree-l%d' classes to match new structure."""
+    for node in toctree.children:
+        if isinstance(node, (addnodes.compact_paragraph, nodes.list_item)):
+            for idx, class_ in enumerate(node['classes']):
+                if class_.startswith('toctree-l'):
+                    node['classes'][idx] = 'toctree-l%d' % (depth - 1)
+            toctree_update_classes(node, depth)
+        elif isinstance(node, nodes.bullet_list):
+            toctree_update_classes(node, depth + 1)
+
+
+def setup(app):
+    app.connect('builder-inited', patch_builder)
+    app.add_config_value('nav_maxdepth', {}, '')
+

docs/api/index.rst

@@ -0,0 +1,12 @@
+=============
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 1
+
+   schematics.models <models>
+   schematics.validation <validation>
+   schematics.transforms <transforms>
+   schematics.types <types>
+   schematics.contrib <contrib>

docs/basics/index.rst

@@ -0,0 +1,11 @@
+======
+Basics
+======
+
+.. toctree::
+   :maxdepth: 1
+
+   Overview <../index>
+   install
+   quickstart
+

docs/conf.py

@@ -17,7 +17,7 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-# sys.path.insert(0, os.path.abspath('..'))
+sys.path.insert(0, os.path.abspath('_ext'))
 
 from schematics import __version__
 
@@ -32,7 +32,9 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'nav']
+
+nav_maxdepth = {'Basics': 1}
 
 doctest_path = [os.path.abspath('..')]
 doctest_test_doctest_blocks = 'default'
@@ -47,7 +49,7 @@
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = 'toc'
 
 # General information about the project.
 project = u'Schematics'
@@ -119,6 +121,8 @@
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
 
+html_context = {'master_doc': 'index'}
+
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #html_logo = None
@@ -204,7 +208,7 @@
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
-#latex_use_parts = False
+latex_use_parts = True
 
 # If true, show page references after internal links.
 #latex_show_pagerefs = False

docs/development/index.rst

@@ -0,0 +1,10 @@
+===========
+Development
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+   development
+   community
+

docs/index.rst

@@ -12,15 +12,6 @@ Schematics
    :target: https://coveralls.io/github/schematics/schematics?branch=development 
    :alt: Coverage
 
-.. toctree::
-   :hidden:
-   :maxdepth: 2
-   :caption: Basics
-
-   Overview <self>
-   basics/install
-   basics/quickstart
-
 .. contents::
    :local:
    :depth: 1
@@ -123,26 +114,6 @@ and easily serialize the results into any format we need.
 The User's Guide provides the high-level concepts, but the API documentation and
 the code itself provide the most accurate reference.
 
-.. toctree::
-   :maxdepth: 2
-   :caption: User's Guide
-
-   usage/types
-   usage/models
-   usage/exporting
-   usage/importing
-   usage/validation
-
-.. toctree::
-   :maxdepth: 1
-   :caption: API Reference
-
-   schematics.models <api/models>
-   schematics.validation <api/validation>
-   schematics.transforms <api/transforms>
-   schematics.types <api/types>
-   schematics.contrib <api/contrib>
-
 
 Development
 ===========
@@ -152,13 +123,6 @@ though.
 
 See the :doc:`development/development` for more information.
 
-.. toctree::
-   :hidden:
-   :caption: Development
-
-   development/development
-   development/community
-
 
 Testing & Coverage
 ==================

docs/toc.rst

@@ -0,0 +1,11 @@
+========
+Contents
+========
+
+.. toctree::
+
+   basics/index
+   usage/index
+   api/index
+   development/index
+

docs/usage/index.rst

@@ -0,0 +1,12 @@
+============
+User's Guide
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   types
+   models
+   exporting
+   importing
+   validation