Adjust docutils container class addition

docs/demo/index.rst

@@ -6,6 +6,51 @@ This is a simple demonstration site to show off a few visual
 and structural elements of the theme. Click the sections on
 the left sidebar to see how various elements look on this theme.
 
+.. div:: container
+
+    .. div:: row
+
+        .. div:: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex
+
+            .. div:: card text-center intro-card shadow my-5 p-2
+
+                .. image:: ../_static/pandas.svg
+                    :class: card-img-top
+                    :height: 52px
+                    :alt: getting started with pandas action icon
+
+                .. div:: card-body flex-fill
+
+                    .. div:: card-title font-weight-bold text-uppercase
+
+                        Getting started
+
+                    .. div:: card-text
+
+                    New to *pandas*? Check out the getting started guides. They
+                    contain an introduction to *pandas'* main concepts and links to
+                    additional tutorials.
+
+        .. div:: col-lg-6 col-md-6 col-sm-6 col-xs-12 d-flex
+
+            .. div:: card text-center intro-card shadow my-5 p-2
+
+                .. image:: ../_static/pandas.svg
+                    :class: card-img-top
+                    :height: 52px
+                    :alt: pandas user guide action icon
+
+                .. div:: card-body flex-fill
+
+                    .. div:: card-title font-weight-bold text-uppercase
+
+                        User Guide
+
+                    .. div:: card-text
+
+                    The user guide provides in-depth information on the key concepts
+                    of pandas with useful background information and explanation.
+
 .. toctree::
     :maxdepth: 2
     :caption: Demo Documentation

pandas_sphinx_theme/__init__.py

@@ -4,6 +4,11 @@
 Adapted for the pandas documentation.
 """
 import os
+import sys
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.parsers.rst import directives
 
 import sphinx.builders.html
 from sphinx.errors import ExtensionError
@@ -166,9 +171,56 @@ def get_html_theme_path():
     theme_path = os.path.abspath(os.path.dirname(__file__))
     return [theme_path]
 
+# -----------------------------------------------------------------------------
+
+# custom div directive
+# see https://github.com/dnnsoftware/Docs/tree/master/common/ext
+
+class DivNode(nodes.General, nodes.Element):
+
+    def __init__(self, text):
+        super(DivNode, self).__init__()
+
+    @staticmethod
+    def visit_div(self, node):
+        self.body.append(self.starttag(node, 'div'))
+
+    @staticmethod
+    def depart_div(self, node=None):
+        self.body.append('</div>\n')
+
+class DivDirective(Directive):
+
+    optional_arguments = 1
+    final_argument_whitespace = True
+    option_spec = {'name': directives.unchanged}
+    has_content = True
+
+    def run(self):
+        self.assert_has_content()
+        text = '\n'.join(self.content)
+        try:
+            if self.arguments:
+                classes = directives.class_option(self.arguments[0])
+            else:
+                classes = []
+        except ValueError:
+            raise self.error(
+                'Invalid class attribute value for "%s" directive: "%s".'
+                % (self.name, self.arguments[0]))
+        node = DivNode(text)
+        node['classes'].extend(classes)
+        self.add_name(node)
+        self.state.nested_parse(self.content, self.content_offset, node)
+        return [node]
+
 
 def setup(app):
     theme_path = get_html_theme_path()[0]
+
+    app.add_node(DivNode, html=(DivNode.visit_div, DivNode.depart_div))
+    app.add_directive('div', DivDirective)
+
     app.add_html_theme("pandas_sphinx_theme", theme_path)
     app.set_translator("html", BootstrapHTML5Translator)