Use custom template (that includes bootstrap) for schema docs

sphinx_asdf/__init__.py

@@ -1,8 +1,11 @@
+import os
+
 from .nodes import add_asdf_nodes
 from .directives import AsdfAutoschemas, AsdfSchema, schema_def
-from .connections import (autogenerate_schema_docs, add_labels_to_nodes,
-                          on_build_finished)
+from .connections import (autogenerate_schema_docs, handle_page_context,
+                          add_labels_to_nodes, on_build_finished)
 
+from sphinx.builders.html import StandaloneHTMLBuilder
 
 
 def setup(app):
@@ -18,9 +21,10 @@ def setup(app):
     add_asdf_nodes(app)
 
     app.add_css_file('sphinx_asdf.css')
-    app.add_javascript('sphinx_asdf.js')
+    app.add_js_file('sphinx_asdf.js')
 
     app.connect('builder-inited', autogenerate_schema_docs)
+    app.connect('html-page-context', handle_page_context)
     app.connect('doctree-read', add_labels_to_nodes)
     app.connect('build-finished', on_build_finished)
 

sphinx_asdf/connections.py

@@ -7,9 +7,13 @@
 from sphinx.util.fileutil import copy_asset
 from sphinx.util.docutils import new_document
 
+from .nodes import schema_doc
 from .directives import schema_def
 
 
+TEMPLATE_PATH = os.path.join(os.path.dirname(__file__), 'templates')
+
+
 def find_autoasdf_directives(env, filename):
 
     parser = RSTParser()
@@ -86,6 +90,13 @@ def autogenerate_schema_docs(app):
     create_schema_docs(app, schemas)
 
 
+def handle_page_context(app, pagename, templatename, ctx, doctree):
+    # Use custom template when rendering pages containing schema documentation.
+    # This allows us to selectively include bootstrap
+    if doctree is not None and doctree.traverse(schema_doc):
+        return os.path.join(TEMPLATE_PATH, 'schema.html')
+
+
 def add_labels_to_nodes(app, document):
     labels = app.env.domaindata['std']['labels']
     anonlabels = app.env.domaindata['std']['anonlabels']

sphinx_asdf/directives.py

@@ -11,7 +11,7 @@
 from sphinx.util.docutils import SphinxDirective
 
 from .md2rst import md2rst
-from .nodes import (toc_link, schema_header_title, schema_title,
+from .nodes import (toc_link, schema_doc, schema_header_title, schema_title,
                     schema_description, schema_properties, schema_property,
                     schema_property_name, schema_property_details,
                     schema_combiner_body, schema_combiner_list,
@@ -92,7 +92,8 @@ def run(self):
 
         title = self._parse_title(schema.get('title', ''), schema_file)
 
-        docnodes = [title]
+        docnodes = schema_doc()
+        docnodes.append(title)
 
         description = schema.get('description', '')
         if description:
@@ -123,7 +124,7 @@ def run(self):
         docnodes.append(section_header(text=ORIGINAL_SCHEMA_SECTION_TITLE))
         docnodes.append(nodes.literal_block(text=raw_content, language='yaml'))
 
-        return docnodes
+        return [docnodes]
 
     def _create_toc(self, schema):
         toc = nodes.compound()

sphinx_asdf/nodes.py

@@ -8,6 +8,16 @@
     """)
 
 
+class schema_doc(nodes.compound):
+    """Marker for the top level of the ASDF schema document"""
+
+    def visit_html(self, node):
+        pass
+
+    def depart_html(self, node):
+        pass
+
+
 class schema_title(nodes.compound):
 
     def visit_html(self, node):
@@ -199,6 +209,7 @@ def depart_html(self, node):
 
 
 custom_nodes = [
+    schema_doc,
     schema_title,
     toc_link,
     schema_header_title,

sphinx_asdf/templates/schema.html

@@ -0,0 +1,5 @@
+{% extends "!page.html" %}
+{% block extrahead %}
+    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/3.4.1/css/bootstrap.min.css" integrity="sha384-HSMxcRTRxnN+Bdg0JdbxYKrThecOKuH5zCYotlSAcp1+c8xmyTe9GYg1l9a69psu" crossorigin="anonymous">
+    <script src="https://stackpath.bootstrapcdn.com/bootstrap/3.4.1/js/bootstrap.min.js" integrity="sha384-aJ21OjlMXNL5UyIl/XNwTMqvzeRMZH2w8c5cRVpzpU8Y5bApTppSuUkhZXN0VxHd" crossorigin="anonymous"></script>
+{% endblock %}