docs: formatting (Update from template)

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/lkubb/salt-template-formula",
-  "commit": "c34a7ebddaf2c656c743180836960318c7e0b6aa",
+  "commit": "c33be7342f32db2e215f929e5a51a690ed445c11",
   "checkout": null,
   "context": {
     "cookiecutter": {

bin/slsdoc

@@ -54,7 +54,8 @@ always_include_default_description = false
 main_heading_char = "="
   # Character to use to underline sub headings
 sub_heading_char = "^"
-"""
+  # Make state IDs literal – ``state.id`` instead of state.id
+literal_sub_heading = false
   # File to write to
 target = "docs/states.rst"
 
@@ -294,6 +295,7 @@ The following states are found in {where}:
         "default_header": "Available States",
         "main_heading_char": "=",
         "sub_heading_char": "-",
+        "literal_sub_heading": False,
     }
 
     def __init__(self, target="docs", prefix=None, basedir=base_dir, opts=None):
@@ -324,6 +326,8 @@ The following states are found in {where}:
         """
         Convenience method to write a subheading
         """
+        if self.opts["literal_sub_heading"]:
+            text = f"``{text}``"
         self._write(text)
         self._write((uline or self.opts["sub_heading_char"]) * len(text))
 

docs/README.rst

@@ -84,8 +84,8 @@ The following states are found in this formula:
    :local:
 
 
-gitea
-^^^^^
+``gitea``
+^^^^^^^^^
 *Meta-state*.
 
 This installs Gitea,
@@ -93,34 +93,34 @@ manages its configuration
 and then starts the ``gitea`` service.
 
 
-gitea.package
-^^^^^^^^^^^^^
+``gitea.package``
+^^^^^^^^^^^^^^^^^
 Installs Gitea only.
 
 Releases are downloaded from the official server by default
 and their signatures verified.
 
 
-gitea.config
-^^^^^^^^^^^^
+``gitea.config``
+^^^^^^^^^^^^^^^^
 Manages Gitea configuration.
 Has a dependency on `gitea.package`_.
 
 
-gitea.service
-^^^^^^^^^^^^^
+``gitea.service``
+^^^^^^^^^^^^^^^^^
 Starts the Gitea service and enables it at boot time.
 Has a dependency on `gitea.config`_.
 
 
-gitea.go
-^^^^^^^^
+``gitea.go``
+^^^^^^^^^^^^
 Creates a build user and downloads Go.
 Required for building Chroma.
 
 
-gitea.mods.rst
-^^^^^^^^^^^^^^
+``gitea.mods.rst``
+^^^^^^^^^^^^^^^^^^
 Compiles `Chroma <https://github.com/alecthomas/chroma>`_ from source
 and installs a Python script that can be setup as an external renderer
 for ``*.rst`` files.
@@ -128,11 +128,11 @@ for ``*.rst`` files.
 Has a dependency on `gitea.go`_.
 
 
-gitea.clean
-^^^^^^^^^^^
+``gitea.clean``
+^^^^^^^^^^^^^^^
 *Meta-state*.
 
-This state will undo everything performed in the ``gitea`` meta-state
+Undoes everything performed in the ``gitea`` meta-state
 in reverse order, i.e.
 stops the service,
 removes the configuration file and then
@@ -141,29 +141,29 @@ Some paths are left to avoid accidental data loss
 (namely ``GITEA_WORKDIR``, ``APP_DATA_PATH`` and the gitea user home).
 
 
-gitea.package.clean
-^^^^^^^^^^^^^^^^^^^
+``gitea.package.clean``
+^^^^^^^^^^^^^^^^^^^^^^^
 Removes Gitea.
 Has a dependency on `gitea.config.clean`_.
 
 
-gitea.config.clean
-^^^^^^^^^^^^^^^^^^
+``gitea.config.clean``
+^^^^^^^^^^^^^^^^^^^^^^
 Removes Gitea configuration. Has a dependency on `gitea.service.clean`_.
 
 
-gitea.service.clean
-^^^^^^^^^^^^^^^^^^^
+``gitea.service.clean``
+^^^^^^^^^^^^^^^^^^^^^^^
 Stops the gitea service and disables it at boot time.
 
 
-gitea.go.clean
-^^^^^^^^^^^^^^
+``gitea.go.clean``
+^^^^^^^^^^^^^^^^^^
 Removes the build user and Go installation.
 
 
-gitea.mods.rst.clean
-^^^^^^^^^^^^^^^^^^^^
+``gitea.mods.rst.clean``
+^^^^^^^^^^^^^^^^^^^^^^^^
 Removes the built ``chroma`` binary, the build path and the
 ``grst`` script.
 

docs/states.rst

@@ -7,8 +7,8 @@ The following states are found in this formula:
    :local:
 
 
-gitea
-^^^^^
+``gitea``
+^^^^^^^^^
 *Meta-state*.
 
 This installs Gitea,
@@ -16,34 +16,34 @@ manages its configuration
 and then starts the ``gitea`` service.
 
 
-gitea.package
-^^^^^^^^^^^^^
+``gitea.package``
+^^^^^^^^^^^^^^^^^
 Installs Gitea only.
 
 Releases are downloaded from the official server by default
 and their signatures verified.
 
 
-gitea.config
-^^^^^^^^^^^^
+``gitea.config``
+^^^^^^^^^^^^^^^^
 Manages Gitea configuration.
 Has a dependency on `gitea.package`_.
 
 
-gitea.service
-^^^^^^^^^^^^^
+``gitea.service``
+^^^^^^^^^^^^^^^^^
 Starts the Gitea service and enables it at boot time.
 Has a dependency on `gitea.config`_.
 
 
-gitea.go
-^^^^^^^^
+``gitea.go``
+^^^^^^^^^^^^
 Creates a build user and downloads Go.
 Required for building Chroma.
 
 
-gitea.mods.rst
-^^^^^^^^^^^^^^
+``gitea.mods.rst``
+^^^^^^^^^^^^^^^^^^
 Compiles `Chroma <https://github.com/alecthomas/chroma>`_ from source
 and installs a Python script that can be setup as an external renderer
 for ``*.rst`` files.
@@ -51,11 +51,11 @@ for ``*.rst`` files.
 Has a dependency on `gitea.go`_.
 
 
-gitea.clean
-^^^^^^^^^^^
+``gitea.clean``
+^^^^^^^^^^^^^^^
 *Meta-state*.
 
-This state will undo everything performed in the ``gitea`` meta-state
+Undoes everything performed in the ``gitea`` meta-state
 in reverse order, i.e.
 stops the service,
 removes the configuration file and then
@@ -64,29 +64,29 @@ Some paths are left to avoid accidental data loss
 (namely ``GITEA_WORKDIR``, ``APP_DATA_PATH`` and the gitea user home).
 
 
-gitea.package.clean
-^^^^^^^^^^^^^^^^^^^
+``gitea.package.clean``
+^^^^^^^^^^^^^^^^^^^^^^^
 Removes Gitea.
 Has a dependency on `gitea.config.clean`_.
 
 
-gitea.config.clean
-^^^^^^^^^^^^^^^^^^
+``gitea.config.clean``
+^^^^^^^^^^^^^^^^^^^^^^
 Removes Gitea configuration. Has a dependency on `gitea.service.clean`_.
 
 
-gitea.service.clean
-^^^^^^^^^^^^^^^^^^^
+``gitea.service.clean``
+^^^^^^^^^^^^^^^^^^^^^^^
 Stops the gitea service and disables it at boot time.
 
 
-gitea.go.clean
-^^^^^^^^^^^^^^
+``gitea.go.clean``
+^^^^^^^^^^^^^^^^^^
 Removes the build user and Go installation.
 
 
-gitea.mods.rst.clean
-^^^^^^^^^^^^^^^^^^^^
+``gitea.mods.rst.clean``
+^^^^^^^^^^^^^^^^^^^^^^^^
 Removes the built ``chroma`` binary, the build path and the
 ``grst`` script.
 

gitea/clean.sls

@@ -3,7 +3,7 @@
 {#-
     *Meta-state*.
 
-    This state will undo everything performed in the ``gitea`` meta-state
+    Undoes everything performed in the ``gitea`` meta-state
     in reverse order, i.e.
     stops the service,
     removes the configuration file and then

pyproject.toml

@@ -28,6 +28,7 @@ The following states are found in this formula:
 """
 main_heading_char = "-"
 sub_heading_char = "^"
+literal_sub_heading = true
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]