Document the {num} role.

docs/conf.py

@@ -27,4 +27,5 @@
         f'https://docs.python.org/{sys.version_info[0]}.{sys.version_info[1]}',
         None,
     ),
+    'sphinx': ('https://www.sphinx-doc.org/en/master', None),
 }

docs/demo/elements.md

@@ -0,0 +1,91 @@
+% Copyright 2024 Remy Blank <remy@c-space.org>
+% SPDX-License-Identifier: MIT
+
+# Elements
+
+## Document metadata
+
+This section configures page metadata with a {rst:dir}`metadata` directive to
+hide solutions by default.
+
+```{metadata}
+hide-solutions: true
+```
+
+## Solutions
+
+This section has several {rst:dir}`solution` blocks, and the page is
+configured to hide solutions by default. Click the "Toggle solutions" button in
+the navbar to show or hide them.
+
+```{solution}
+This solution follows the per-page setting.
+```
+
+```{solution} *Complete* solution
+This solution has a custom title.
+```
+
+```{solution} Solution (show)
+:show:
+This solution is always visible.
+```
+
+```{solution} Solution (expand)
+:expand:
+This solution is expanded by default.
+```
+
+```{solution}
+:class: warning
+This solution has a different color, and no drop-down.
+```
+
+## IFrames
+
+The [YouTube](https://youtube.com/) video below is embedded with the
+{rst:dir}`youtube` directive.
+
+```{youtube} aVwxzDHniEw
+```
+
+The [GeoGebra](https://geogebra.org/) sheet below is embedded with the
+{rst:dir}`iframe` directive.
+
+```{iframe} https://www.geogebra.org/classic/esdhdhzd
+```
+
+## Numbering
+
+This sections uses the {rst:role}`num` role to create numbered sub-sections that
+reference each other, and separately numbered quotes.
+
+### Exercise {num}`ex:first`
+
+Read these quotes, then move on to exercises {numref}`ex:second` &
+{numref}`ex:third`.
+
+{attribution="Terry Pratchett, Mort"}
+> **Quote {num}`quote`:** "It would seem that you have no useful skill or talent
+> whatsoever," he said. "Have you thought of going into teaching?""
+
+{attribution="Terry Pratchett, Hogfather"}
+> **Quote {num}`quote`:** Real stupidity beats artificial intelligence every
+> time.
+
+### Exercise {num}`ex:second`
+
+You've already read the quotes from {numref}`exercise %s<ex:first>`. Read this
+one as well, the move to {numref}`exercise %s<ex:third>`.
+
+{attribution="Douglas Adams, The Hitchhiker’s Guide to the Galaxy"}
+> **Quote {num}`quote`:** For a moment, nothing happened. Then, after a second
+> or so, nothing continued to happen.
+
+### Exercise {num}`ex:third`
+
+This is the last quote.
+
+{attribution="Iain M. Banks, Consider Phlebas"}
+> **Quote {num}`quote`:** I had nightmares I thought were really horrible until
+> I woke up and remembered what reality was at the moment.

docs/demo/index.md

@@ -5,7 +5,7 @@
 
 ```{toctree}
 :maxdepth: 1
-directives
+elements
 python
 sql
 html

docs/reference/directives.md → docs/reference/elements.md

@@ -1,7 +1,7 @@
 % Copyright 2024 Remy Blank <remy@c-space.org>
 % SPDX-License-Identifier: MIT
 
-# Directives
+# Elements
 
 ## Document metadata
 
@@ -132,4 +132,28 @@ assistive technologies.
 
 ## Code execution
 
-See "[Code execution](exec.md)".
+See "[](exec.md)".
+
+## Numbering
+
+````{rst:role} num
+This role performs automatic numbering, optionally creating reference targets.
+The role content is either a label (e.g. `` {num}`label` ``) or an explicit
+title and a label (e.g. `` {num}`Exercise %s<label>` ``). In the latter case,
+the title must contain the string `%s`, which gets substituted with the number.
+
+The label is composed of a counter identifier and an optional target name,
+separated by `:`. Distinct identifiers are numbered separately, and the counters
+persist across pages. Instances with a target (e.g. `` {num}`ex:target` ``) can
+be referenced with the {rst:role}`numref` role (e.g. `` {numref}`ex:target` ``).
+
+```{code-block} md
+## Exercise {num}`ex:intro`
+
+As an introduction to ...
+
+## Exercise {num}`ex`
+
+After completing {numref}`exercise %s<ex:intro>`, ...
+```
+````

docs/reference/index.md

@@ -5,7 +5,7 @@
 
 ```{toctree}
 :maxdepth: 1
-directives
+elements
 exec
 python-libs
 ```

tdoc/common/static/tdoc/styles.css.jinja

@@ -26,6 +26,11 @@ div.sidebar, aside.sidebar {
     background-color: var(--pst-color-table-row-hover-bg);
 }
 
+/* Make quotation attributions a bit more compact. */
+blockquote div > p:has(+ p.attribution) {
+    margin-bottom: 0;
+}
+
 /* Admonitions */
 .admonition.dropdown .admonition-title {
     cursor: pointer;