🐛 FIX: Add formatting for definition/field/apidoc lists

.readthedocs.yml

@@ -8,3 +8,7 @@ python:
         extra_requirements:
           - sphinx
       - requirements: docs/requirements.txt
+
+sphinx:
+  builder: html
+  fail_on_warning: true

docs/api/index.rst

@@ -0,0 +1,13 @@
+.. _api/main:
+
+Python API
+==========
+
+.. autodata:: sphinx_book_theme.__version__
+
+.. autoclass:: sphinx_book_theme.Margin
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autofunction:: sphinx_book_theme.launch.add_hub_urls

docs/conf.py

@@ -17,6 +17,9 @@
     "sphinx_togglebutton",
     "sphinxcontrib.bibtex",
     "sphinx_thebe",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -27,6 +30,15 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.8", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/3.x", None),
+}
+nitpick_ignore = [
+    ("py:class", "docutils.nodes.document"),
+    ("py:class", "docutils.parsers.rst.directives.body.Sidebar"),
+]
+
 numfig = True
 
 # -- Options for HTML output -------------------------------------------------

docs/index.md

@@ -58,6 +58,7 @@ GitHub repository <https://github.com/executablebooks/sphinx-book-theme>
 :maxdepth: 2
 
 reference/index
+api/index
 ```
 
 ## Acknowledgements

docs/reference/demo.rst

@@ -24,7 +24,7 @@ citation references ([12]_), substitution references (|example|), and _`inline h
 (although exceedingly ugly!) in *re*\ ``Structured``\ *Text*. Problems are indicated by problematic
 text (generated by processing errors; this one is intentional).
 
-Also with ``sphinx.ext.autodoc``, which I use in the demo, I can link to :class:`test_py_module.test.Foo`.
+Also with ``sphinx.ext.autodoc``, which I use in the demo, I can link to :py:data:`sphinx_book_theme.__version__`.
 It will link you right my code documentation for it.
 
 The default role for interpreted text is `Title Reference`.  Here are some explicit interpreted text roles:
@@ -143,6 +143,33 @@ Block quotes consist of indented body elements:
 
     -- Anne Elk (Miss)
 
+Definition and Field Lists
+--------------------------
+
+Definition list:
+
+what
+  Definition lists associate a term with
+  a definition.
+
+how
+  The term is a one-line phrase, and the
+  definition is one or more paragraphs or
+  body elements, indented relative to the
+  term. Blank lines are not allowed
+  between term and definition.
+
+Field List:
+
+:Authors:
+    Tony J. (Tibs) Ibbs,
+    David Goodger
+
+    (and sundry other good-natured folks)
+
+:Version: 1.0 of 2001/08/08
+:Dedication: To my father.
+
 Doctest Blocks
 --------------
 

noxfile.py

@@ -46,7 +46,9 @@ def compile_scss(session):
 def docs(session):
     """Build documentation for this project."""
     session.install(".[sphinx]")
-    session.run("sphinx-build", "-b", "html", "docs", "docs/_build/html")
+    session.run(
+        "sphinx-build", "-nW", "--keep-going", "-b", "html", "docs", "docs/_build/html"
+    )
 
     session.notify("compile-scss")
 
@@ -69,6 +71,6 @@ def docs_live(session):
             # open the browser after 5 seconds
             "--open-browser",
             # sphinx-build arguments
-            "-a", "-b", "html", "docs", "docs/_build/html",
+            "-a", "-n", "-b", "html", "docs", "docs/_build/html",
         )
         # fmt: on

setup.py

@@ -46,7 +46,7 @@
             "ipywidgets",
             "pandas",
             "nbclient",
-            "myst-nb",
+            "myst-nb~=0.9.1",
             "sphinx-togglebutton>=0.2.1",
             "sphinx-copybutton",
             "plotly",

sphinx_book_theme/__init__.py

@@ -9,6 +9,8 @@
 from .launch import add_hub_urls
 
 __version__ = "0.0.35"
+"""sphinx-book-theme version"""
+
 SPHINX_LOGGER = logging.getLogger(__name__)
 
 
@@ -289,6 +291,7 @@ class Margin(directives.body.Sidebar):
     required_arguments = 0
 
     def run(self):
+        """Run the directive."""
         if not self.arguments:
             self.arguments = [""]
         nodes = super().run()

sphinx_book_theme/launch.py

@@ -1,13 +1,33 @@
 from pathlib import Path
+from typing import Any, Dict, Optional
+
+from docutils.nodes import document
+from sphinx.application import Sphinx
 from sphinx.util import logging
 from shutil import copy2
 
 
 SPHINX_LOGGER = logging.getLogger(__name__)
 
 
-def add_hub_urls(app, pagename, templatename, context, doctree):
-    """Builds a binder link and inserts it in HTML context for use in templating."""
+def add_hub_urls(
+    app: Sphinx,
+    pagename: str,
+    templatename: str,
+    context: Dict[str, Any],
+    doctree: Optional[document],
+):
+    """Builds a binder link and inserts it in HTML context for use in templating.
+
+    This is a ``html-page-context`` sphinx event (see :ref:`sphinx:events`).
+
+    :param pagename: The sphinx docname related to the page
+    :param context: A dictionary of values that are given to the template engine,
+        to render the page and can be modified to include custom values.
+    :param doctree: A doctree when the page is created from a reST documents;
+        it will be None when the page is created from an HTML template alone.
+
+    """
 
     # First decide if we'll insert any links
     path = app.env.doc2path(pagename)