Use custom parser for Sphinx with support for Nikola titles

docs/sphinx/conf.py

@@ -1,5 +1,9 @@
 # -*- coding: utf-8 -*-
-#
+
+from __future__ import unicode_literals
+import os
+import sys
+
 # Nikola documentation build configuration file, created by
 # sphinx-quickstart on Sun Sep 22 17:43:37 2013.
 #
@@ -15,19 +19,17 @@
 # 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(os.path.dirname(__file__)))
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 # needs_sphinx = '1.0'
 
-from __future__ import unicode_literals
-
 # 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.mathjax']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'nikola_titles_for_sphinx']
 # extensions.append('sphinxcontrib.gist')
 
 # Add any paths that contain templates here, relative to this directory.
@@ -36,6 +38,8 @@
 # The suffix of source filenames.
 source_suffix = '.rst'
 
+source_parsers = {'.rst': 'nikola_titles_for_sphinx.NikolaTitlesRSTParser'}
+
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
 

docs/sphinx/index.rst

@@ -22,6 +22,7 @@ visible in this version of Nikola docs.
    internals
    social_buttons
    path_handlers
+   support
 
 .. toctree::
    :maxdepth: 5

docs/sphinx/nikola_titles_for_sphinx.py

@@ -0,0 +1,32 @@
+import sphinx.parsers
+from docutils.statemachine import StringList
+from typing import TYPE_CHECKING, Any, Dict, List, Type, Union
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+TITLE_MARKER = ".. title:"
+
+
+class NikolaTitlesRSTParser(sphinx.parsers.RSTParser):
+    def decorate(self, content: StringList) -> None:
+        """Preprocess reST content before parsing."""
+        super().decorate(content)
+        for line in content[:20]:
+            if line.startswith(TITLE_MARKER):
+                title = line[len(TITLE_MARKER) :].strip()
+                fence = "=" * len(title)
+                content.insert(0, "", "<generated>", 0)
+                content.insert(0, fence, "<generated>", 0)
+                content.insert(0, title, "<generated>", 0)
+                content.insert(0, fence, "<generated>", 0)
+
+
+def setup(app: "Sphinx") -> Dict[str, Any]:
+    app.add_source_parser(NikolaTitlesRSTParser, override=True)
+
+    return {
+        "version": "0.1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

docs/sphinx/requirements-docs.txt

@@ -1,2 +1,4 @@
 -r ../../requirements-extras.txt
+-e ../..
 pyparsing>=2.0.2
+Sphinx>=4.2.0