docs proofreading; more inline syntax highlighting

includes external links to RST doctree specs

docs/admonitions.rst

@@ -2,7 +2,7 @@
 Admonitions
 ===========
 
-This theme uses the ``admonition`` directives for Sphinx admonitions.
+This theme uses the :dutree:`admonition` directives for Sphinx admonitions.
 
 rST and Sphinx
 **************
@@ -14,92 +14,92 @@ usage in other sphinx-based themes. They are:
 .. rst-example:: ``note``, ``todo``, ``seealso``
 
    .. seealso::
-      This admonition is specific to Sphinx directives and not defined in the rST specifications
-      as you can `seealso`.
+      This admonition is specific to Sphinx directives and not defined in the reStructuredText
+      specifications as you can `seealso`. The `todo` admonition is also defined by Sphinx.
 
-      ``note`` and ``todo`` are admonitions defined by the rST specifications.
+      The :dutree:`note` admonition *is* defined by the reStructuredText specifications.
 
 .. rst-example:: ``tip``, ``hint``, ``important``
 
    .. important::
-      It is **important** to correctly use admonitions.
+      It is :dutree:`important` to correctly use admonitions.
 
 .. rst-example:: ``attention``, ``caution``, ``warning``
 
    .. warning::
-      This is a **warning**.
+      This is a :dutree:`warning`.
 
 .. rst-example:: ``danger``, ``error``
 
    .. error::
-      You have made a grave **error**.
+      You have made a grave :dutree:`error`.
 
 Admonitions from mkdocs-material
 ********************************
 
 Some additional admonitions are supported via the source code from the mkdocs-material theme.
 These admonitions can still be used, but the syntax is a little different because it relies
-on the generic admonition defined in the reStructuredText specifications.
+on the generic :dutree:`admonition` defined in the reStructuredText specifications.
 
 To use the following admonitions' styles from the mkdocs-material theme, the rST syntax is
-shown to demonstrate using the ``:class:`` option of generic admonitions.
+shown to demonstrate using the :rst:`:class:` option of generic admonitions.
 
 .. important::
-   The ``:class:`` options below (in the rST code blocks) must use lower case letters for the
+   The :rst:`:class:` options below (in the rST code blocks) must use lower case letters for the
    styling to work. Otherwise, the admonition will look like a `note` (as that is the
    default fallback style).
 
-.. rst-example:: ``todo``, ``info``
+.. rst-example:: :css:`todo`, :css:`info`
 
    .. admonition:: Info
       :class: info
 
-      Thanks to the mkdocs-material theme, the ``todo`` class is also an alias of the
-      ``info`` class when not using the `.. todo:: <todo>` directive.
+      Thanks to the mkdocs-material theme, the :css:`todo` class is also an alias of
+      the :css:`info` class when not using the `todo` directive.
 
-.. rst-example:: ``abstract``, ``summary``, ``tldr``
+.. rst-example:: :css:`abstract`, :css:`summary`, :css:`tldr`
 
    .. admonition:: TL;DR
       :class: tldr
 
-      The ``:class: tldr`` part is important.
+      The :rst:`:class: tldr` part is important.
 
-.. rst-example:: ``success``, ``check``, ``done``
+.. rst-example:: :css:`success`, :css:`check`, :css:`done`
 
    .. admonition:: Accomplished
       :class: done
 
-      This style is used for ``success``, ``check``, ``done`` CSS classes.
+      This style is used for :css:`success`, :css:`check`, :css:`done` CSS classes.
 
-.. rst-example:: ``question``, ``help``, ``faq``
+.. rst-example:: :css:`question`, :css:`help`, :css:`faq`
 
    .. admonition:: FAQ
       :class: faq
 
       Helpful advice goes here.
 
-.. rst-example:: ``failure``, ``fail``, ``missing``
+.. rst-example:: :css:`failure`, :css:`fail`, :css:`missing`
 
    .. admonition:: Something Missing
       :class: missing
 
       We expected some loss of feature-coverage.
 
-.. rst-example:: ``bug``
+.. rst-example:: :css:`bug`
 
    .. admonition:: Known Bug
       :class: bug
 
       Bug reported data/conclusion.
 
-.. rst-example:: ``example``
+.. rst-example:: :css:`example`
 
    .. admonition:: Example Admonition
       :class: example
 
       Example Body.
 
-.. rst-example:: ``cite``, ``quote``
+.. rst-example:: :css:`cite`, :css:`quote`
 
    .. admonition:: Unknown Quote
       :class: quote
@@ -122,7 +122,7 @@ The `sphinxcontrib-details-directive extension`_ should be added to conf.py's ex
 
    extensions = ["sphinx_immaterial", "sphinxcontrib.details.directive"]
 
-If the ``:class:`` option is not supplied to the ``details`` directive then the admonition
+If the :rst:`:class:` option is not supplied to the ``details`` directive then the admonition
 style falls back to a `note` admonition style.
 
 .. rst-example::
@@ -131,14 +131,14 @@ style falls back to a `note` admonition style.
       :class: example
       :open:
 
-      Use the ``:open:`` option as a flag to expand the admonition by default.
+      Use the :rst:`:open:` option as a flag to expand the admonition by default.
 
 .. rst-example::
 
    .. details:: Closed by default
       :class: help
 
-      Without the ``:open:`` flag, the admonition is collapsed by default.
+      Without the :rst:`:open:` flag, the admonition is collapsed by default.
 
 Removing the title
 ******************
@@ -148,25 +148,25 @@ from an admonition, this theme has an added directive to do just that: ``md-admo
 
 The admonition's title can be removed if the ``md-admonition`` directive is not provided
 any arguments. Because the ``md-admonition`` directive is an adaptation of the generic
-``admonition`` directive, the ``class`` option is still respected.
+:dutree:`admonition` directive, the :rst:`:class:` option is still respected.
 
 .. rst-example::
 
    .. md-admonition::
       :class: error
 
-      This example uses the styling of the ``error`` admonition
+      This example uses the styling of the :css:`error` admonition
 
 .. rst-example::
 
    .. md-admonition:: Using a title
       :class: help
 
-      This example uses the styling of the ``help`` admonition
+      This example uses the styling of the :css:`help` admonition
 
 .. hint::
-   You can use the ``md-admonition`` directive in other themes by adding the theme's module to your
-   ``extensions`` list in *conf.py*
+   You can use the ``md-admonition`` directive in other Sphinx themes by adding the theme's module to
+   your `extensions` list in *conf.py*
 
    .. code-block:: python
 
@@ -212,8 +212,8 @@ folder and add the new CSS to an additional style sheet.
 Changing the Admonition Icon
 ----------------------------
 
-Any of the above builtin admonitions' icons can be changed using the :themeconf:`icon`\ [:themeconf:`admonition`\ ] field in
-:confval:`html_theme_options` configuration.
+Any of the above builtin admonitions' icons can be changed using the
+:themeconf:`icon`\ [:themeconf:`admonition`] field in :confval:`html_theme_options` settings.
 
 .. code-block:: python
    :caption: Changing the `note` icon in conf.py
@@ -224,7 +224,7 @@ Any of the above builtin admonitions' icons can be changed using the :themeconf:
                "note": "material/file-document-outline",
            },
        },
-   },
+   }
 
 .. admonition:: ``seealso`` uses the ``note`` icon
    :class: missing

docs/conf.py

@@ -204,6 +204,10 @@
         "https://graphviz.org/docs/attrs/%s/",
         "%s attribute",
     ),
+    "dutree": (
+        "https://docutils.sourceforge.io/docs/ref/doctree.html#%s",
+        "%s",
+    ),
 }
 
 object_description_options = []

docs/customization.rst

@@ -110,7 +110,7 @@ Metadata for a single page
 ==========================
 
 Each page can support a set of page-specific options. These are configured using metadata roles.
-Each metadata is evaluated as a ``:key: value`` pair.
+Each metadata is evaluated as a :rst:`:key: value` pair.
 
 .. seealso::
     Review the
@@ -122,7 +122,7 @@ Each metadata is evaluated as a ``:key: value`` pair.
     Unlike, newer versions of mkdocs-material theme, this theme also supports the use of a textual
     "hero" section.
 
-    To set the hero's text for an individual page, use the ``:hero:`` metadata field for the desired page.
+    To set the hero's text for an individual page, use the :rst:`:hero:` metadata field for the desired page.
     If not specified, then the page will not have a hero section.
 
     .. code-block:: rst
@@ -152,7 +152,7 @@ Each metadata is evaluated as a ``:key: value`` pair.
 
         :hide_toc:
 
-    Instead of using ``:hide_toc:``, this theme can also use the ``:tocdepth:`` metadata to hide the
+    Instead of using :rst:`:hide_toc:`, this theme can also use the :rst:`:tocdepth:` metadata to hide the
     page's Table of Contents.
 
     .. code-block:: rst
@@ -239,9 +239,9 @@ Configuration Options
 
         .. themeconf:: repo
 
-            The icon that represents the source code repository can be changed using the ``repo`` field of the
-            ``icon`` `dict` (within the `html_theme_options` `dict`). Although this icon can be
-            `any of the icons bundled with this theme`_,
+            The icon that represents the source code repository can be changed using the
+            :themeconf:`icon`\ [:themeconf:`repo`] field in the :confval:`html_theme_options`
+            settings. Although this icon can be `any of the icons bundled with this theme`_,
             popular choices are:
 
             - |fa-git| ``fontawesome/brands/git``
@@ -840,13 +840,13 @@ This theme has a new block inherited from the mkdocs-material theme:
     Previous and next in the footer.
 
 ``announce``
-    An announcement can be added to the top of the page using by extending this theme's base.html
+    An announcement can be added to the top of the page by extending this theme's base.html
     template. For example, this theme uses the following custom template to add an announcement
     (`scroll to top to see it in action <#>`_).
 
     .. literalinclude:: _templates/base.html
         :caption: docs/_templates/base.html
         :language: jinja
 
-    Optionally, add the ``announce.dismiss`` in the :themeconf:`features` list to let readers
-    dismiss the announcement banner.
+    Optionally, add the :python:`"announce.dismiss"` in the :themeconf:`features` list to let readers
+    dismiss the announcement banner.