From ad8e43e57e84c848b2e1e7d1c8c4688ff6810004 Mon Sep 17 00:00:00 2001
From: Elliot Fontaine <92150839+elliotfontaine@users.noreply.github.com>
Date: Mon, 22 Jul 2024 16:03:45 +0200
Subject: [PATCH] clean up docs

---
 docs/source/development/add_config_option.rst |  4 +-
 docs/source/development/coding_style.rst      | 42 +++++++++----------
 docs/source/substitutions.rst.include         |  3 --
 3 files changed, 23 insertions(+), 26 deletions(-)

diff --git a/docs/source/development/add_config_option.rst b/docs/source/development/add_config_option.rst
index 5f9d141..bb92d52 100644
--- a/docs/source/development/add_config_option.rst
+++ b/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.
diff --git a/docs/source/development/coding_style.rst b/docs/source/development/coding_style.rst
index 2e1933b..324197b 100644
--- a/docs/source/development/coding_style.rst
+++ b/docs/source/development/coding_style.rst
@@ -1,8 +1,8 @@
 .. _development.coding-style:
 
-==========================================
-Coding styles for Python, R, Bash and Cylc
-==========================================
+============
+Coding style
+============
 
 :file:`bin/` scripts: environment variables or command line arguments?
 ======================================================================
@@ -10,27 +10,10 @@ Coding styles for Python, R, Bash and Cylc
 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]
diff --git a/docs/source/substitutions.rst.include b/docs/source/substitutions.rst.include
index 6a4aaf1..742a675 100644
--- a/docs/source/substitutions.rst.include
+++ b/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