clean up docs

docs/source/development/add_config_option.rst

@@ -41,8 +41,8 @@ In the :strong:`[validate_cfg]` task, change the :strong:`metadata` environment
 During run installation, the value will now be replaced by the one set in :rose:file:`rose-suite.conf`.
 If you want to change the value at runtime, you can follow the instructions in :ref:`tutorial.user-config`.
 
-Adding validation for the new configuration item
-================================================
+Validate the new configuration item
+===================================
 
 Rose (the configuration manager) allows us to validate the user configuration. It is done at runtime
 at cyclepoint 0 with the :strong:`[validate_cfg]` task. Let's add a new validation rule for our item.

docs/source/development/coding_style.rst

@@ -1,36 +1,19 @@
 .. _development.coding-style:
 
-==========================================
-Coding styles for Python, R, Bash and Cylc
-==========================================
+============
+Coding style
+============
 
 :file:`bin/` scripts: environment variables or command line arguments?
 ======================================================================
 
 When writing scripts (Python, R, Bash) for the workflow, you have the choice between loading
 environment variables from inside the script, or parsing command line arguments.
 
-On a rule of thumb, use environment variables when you don't expect the script to be reused outside
+As a rule of thumb, use environment variables when you don't expect the script to be reused outside
 the workflow, and command line arguments with strong input validation when you want to make the script
 more portable.
 
-Python
-======
-
-Python code should follow the `PEP 8`_ style guide. The `Black`_ code formatter should be used to
-automatically format the code.
-
-You should also use a linter / static code analyser like `Pylint`_ to catch potential bugs, commented
-out code, code smells, etc.
-
-R 
-=
-[TODO]
-
-Bash
-====
-[TODO]
-
 Cylc
 ====
 
@@ -75,3 +58,20 @@ do it in the :strong:`[environment]` block of the task, not in the script itself
                     if the shape of the flowgram is not stable at the beginning or end of the run.
                 """
                 categories = bioinformatics
+
+Python
+======
+
+Python code should follow the `PEP 8`_ style guide. The `Black`_ code formatter should be used to
+automatically format the code.
+
+You should also use a linter / static code analyser like `Pylint`_ to catch potential bugs, commented
+out code, code smells, etc.
+
+Bash
+====
+[TODO]
+
+R 
+=
+[TODO]

docs/source/substitutions.rst.include

@@ -2,15 +2,12 @@
 
 .. Hyperlinks
 
-.. _Cylc User Guide: https://cylc.github.io/cylc-doc/latest/html/index.html
-.. _Cylc Workflow Design Guide: https://cylc.github.io/cylc-doc/latest/html/workflow-design-guide/index.html
 .. _Cylc: https://cylc.github.io/
 .. _fia: https://en.wikipedia.org/wiki/Flow_injection_analysis
 .. _PEP 8: https://peps.python.org/pep-0008/
 .. _Black: https://black.readthedocs.io/en/stable/
 .. _Pylint: https://pylint.pycqa.org/en/latest/
 
-
 .. Substitutions