docs/contrib: doc: Add headings section, shellcode
@@ -15,7 +15,7 @@ example:
One asterisk: *text* for emphasis (italics),
Two asterisks: **text** for strong emphasis (boldface), and
- Backquotes: ``text`` for code samples.
+ Double backquotes: ``text`` for code samples.
.. __: https://www.sphinx-doc.org/en/master/
@@ -53,8 +53,8 @@ If you have made any changes to the stylesheets, you need to install the
.. code-block:: bash
- apt install sassc
- make css
+ $ apt install sassc
+ $ make css
.. __: https://github.com/sass/sassc
@@ -73,6 +73,34 @@ First and foremost, see the
.. _a link: https://domain.invalid/
+**Headings:**
+
+Headings must always be *underlined* with at least as many characters as the
+text is wide.
+
+.. code-block:: rst
+
+ Page title
+ ==========
+
+Use page title only once per file (at the top). This is also the name that the
+page will appear under.
+
+.. code-block:: rst
+
+ Section heading (h3)
+ --------------------
+
+Use section heading to divide page into sections
+
+.. code-block:: rst
+
+ Sub-Heading (h4)
+ ^^^^^^^^^^^^^^^^
+
+Use sub-heading only if necessary - if you need this many levels of headings,
+maybe the content chould better be spread out across multiple articles
+
**Referencing other sections:** (see `:ref:`__)
.. code-block:: rst
@@ -104,9 +132,9 @@ Use ``.. code-block:: <language>`` and indent the code by one level:
.. code-block:: bash
- sudo apt install python3 python3-pip python3-virtualenv
- virtualenv .venv
- source .venv/bin/activate
+ $ sudo apt install python3 python3-pip python3-virtualenv
+ $ virtualenv .venv
+ $ source .venv/bin/activate
(.venv) $ python [cmd]
Syntax standards
