Add documentation for recipe elements

- document all existing elements and how to use them
- some smallish fixes to existing documentation
- add autosectionlabel extension to Sphinx configuration
  to enable better crossreferences.
- add config file for readthedocs.io.

.readthedocs.yaml

@@ -0,0 +1,33 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: doc/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+   - pdf
+#    - epub
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt

doc/101.rst

@@ -226,8 +226,8 @@ Examples
 
 For example, in case of :xml:`<checkbox action="enable" />` on "unchecked"
 and "clickable" (not greyed-out) checkbox:
- * `action` - clicking on the checkbox
- * `desired state` - checkbox is "checked"
+* `action` - clicking on the checkbox
+* `desired state` - checkbox is "checked"
 
 In this case (action="enable"), checkbox that is already checked is not
 clicked on because it's already in `desired state`. Clicking on it would make

doc/conf.py

@@ -33,6 +33,7 @@
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
+    'sphinx.ext.autosectionlabel'
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -263,3 +264,6 @@
 #texinfo_no_detailmenu = False
 
 sys.path.append("../")
+
+# Make sure the target is unique
+autosectionlabel_prefix_document = True

doc/index.rst

@@ -52,6 +52,7 @@ Contents
    decorators
    history
    debugging
+   recipe_elements/index
 
 
 Indices and tables