closes #228 improving our code syntax highlighting and formatting

Author: kinow

conf.py

@@ -58,8 +58,6 @@
 
 master_doc = 'index'
 
-pygments_style = 'borland'
-
 # Set the default role so we can use `foo` instead of ``foo``
 default_role = 'literal'
 
@@ -95,9 +93,18 @@
 
 # -- Options for Pygments ----------------------------------------------------
 
+pygments_style = 'default'
+
 # TODO: maybe write our own lexer to customize tokens, keywords, etc?
 lexers['cwl'] = YamlLexer()
 
+highlight_options = {
+  'default': {
+      'stripall': True
+  },
+  'bash': {'startinline': True},
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

prerequisites.md

@@ -39,7 +39,10 @@ like `venv` or `conda`. The following commands will create and activate a Python
 virtual environment using the `venv` module, and install `cwltool` in that
 environment:
 
-```bash
+```{code-block} console
+:name: installing-cwltool-with-pip-and-venv
+:caption: Installing `cwltool` with `pip` and `venv`.
+
 $ python -m venv venv
 $ source venv/bin/activate
 $ (venv) pip install cwltool
@@ -54,15 +57,22 @@ Let's use a simple workflow `true.cwl` with `cwltool`.
 
 ```{literalinclude} /_includes/cwl/simplest_cwl.cwl
 :language: cwl
+:caption: "`true.cwl`"
+:name: truecwl-file
 ```
-<p class="text-center text-muted mt-n2">true.cwl</p>
 
-First you can validate the CWL document:
+The `cwltool` command has an option to validate CWL workflows. It will parse the
+CWL workflow, look for syntax errors, and verify that the workflow is compliant
+with the CWL specification, without running the workflow. To use it you just need
+to pass `--validate` to the `cwltool` command:
 
 % TODO: maybe figure out a way to avoid /home/kinow/ etc. in the documentation
 %       to avoid multiple user-names/directory-locations varying in the docs.
 
-```bash
+```{code-block} console
+:name: validating-truecwl-with-cwltool
+:caption: Validating `true.cwl` with `cwltool`.
+
 $ cwltool --validate true.cwl
 INFO /home/kinow/Development/python/workspace/user_guide/venv/bin/cwltool 3.1.20220406080846
 INFO Resolved 'true.cwl' to 'file:///tmp/true.cwl'
@@ -71,7 +81,10 @@ true.cwl is valid CWL.
 
 You can run the CWL workflow now that you know it is valid:
 
-```bash
+```{code-block} console
+:name: running-truecwl-with-cwltool
+:caption: Running `true.cwl` with `cwltool`.
+
 $ cwltool true.cwl
 INFO /home/kinow/Development/python/workspace/user_guide/venv/bin/cwltool 3.1.20220406080846
 INFO Resolved 'true.cwl' to 'file:///tmp/true.cwl'
@@ -81,7 +94,7 @@ INFO [job true.cwl] completed success
 INFO Final process status is success
 ```
 
-### cwl-runner
+### cwl-runner Python module
 
 `cwl-runner` is an implementation agnostic alias for CWL Runners.
 Users can invoke `cwl-runner` instead of invoking a CWL runner like `cwltool`
@@ -93,7 +106,10 @@ The CWL community publishes a Python module with the same name,
 the rest of this user guide. You can use `pip` to install the `cwl-runner`
 Python module:
 
-```bash
+```{code-block} console
+:name: installing-cwlrunner-with-pip
+:caption: Installing `cwl-runner` with `pip`.
+
 $ pip install cwl-runner
 ```
 
@@ -104,14 +120,20 @@ Now you can validate and run your workflow with `cwl-runner` executable,
 which will invoke `cwltool`. You should have the same results and output
 as in the previous section.
 
-```bash
+```{code-block} console
+:name: validating-truecwl-with-cwl-runner
+:caption: Validating `true.cwl` with `cwl-runner`.
+
 $ cwl-runner --validate true.cwl
 INFO /home/kinow/Development/python/workspace/user_guide/venv/bin/cwl-runner 3.1.20220406080846
 INFO Resolved 'true.cwl' to 'file:///tmp/true.cwl'
 true.cwl is valid CWL.
 ```
 
-```bash
+```{code-block} console
+:name: running-truecwl-with-cwl-runner
+:caption: Running `true.cwl` with `cwl-runner`.
+
 $ cwl-runner true.cwl
 INFO /home/kinow/Development/python/workspace/user_guide/venv/bin/cwl-runner 3.1.20220406080846
 INFO Resolved 'true.cwl' to 'file:///tmp/true.cwl'
@@ -127,15 +149,19 @@ a special first line, a *shebang*:
 
 ```{literalinclude} /_includes/cwl/simplest_cwl_shebang.cwl
 :language: cwl
+:name: cwltool-with-a-shebang
+:caption: "`cwltool` with a shebang"
 ```
-<p class="text-center text-muted mt-n2">true.cwl</p>
 
 Now, after you make the file `true.cwl` executable with `chmod u+x`,
 you can execute it directly in the command-line and the program
 specified in the shebang (`cwl-runner`) will be used to execute the
 rest of the file.
 
-```bash
+```{code-block} console
+:name: making-truecwl-executable-and-running-it
+:caption: Making `true.cwl` executable and running it.
+
 $ chmod u+x true.cwl
 $ ./true.cwl
 INFO /home/kinow/Development/python/workspace/user_guide/venv/bin/cwl-runner 3.1.20220406080846

quick-start.md

@@ -19,8 +19,9 @@ with comments:
 
 ```{literalinclude} /_includes/cwl/hello_world.cwl
 :language: cwl
+:name: hello_worldcwl
+:caption: "`hello_world.cwl`"
 ```
-<p class="text-center text-muted mt-n2">hello_world.cwl</p>
 
 The example above is just a wrapper for the `echo` command-line tool.
 Running the workflow above with the default input values, produces the
@@ -39,8 +40,11 @@ CWL *Reference Runner* for the specification, and compliant with the
 latest version of the specification, {{ cwl_version }}. You can install
 `cwltool` using `pip`:
 
-```bash
-pip install cwltool
+```{code-block} console
+:name: installing-cwltool-with-pip
+:caption: Installing `cwltool` with `pip`.
+
+$ pip install cwltool
 ```
 
 ```{note}
@@ -55,7 +59,10 @@ The usage of the `cwltool` command-line executable is basically
 `cwltool [OPTIONS] <CWL_DOCUMENT> [INPUTS_OBJECT]`. You can run the
 `hello_world.cwl` workflow without specifying any option:
 
-```bash
+```{code-block} console
+:name: running-hello_worldcwl-with-cwltool
+:caption: Running `hello_world.cwl` with `cwltool`.
+
 $ cwltool hello_world.cwl
 INFO /tmp/venv/bin/cwltool 3.1.20220628170238
 INFO Resolved 'hello_world.cwl' to 'file:///tmp/hello_world.cwl'
@@ -70,7 +77,10 @@ INFO Final process status is success
 Or you can override the default value of the input parameter `message`, similar
 to how you would change the argument of the `echo` base command:
 
-```bash
+```{code-block} console
+:name: running-hello_worldcwl-with-cwltool-passing-an-input-parameter
+:caption: Running `hello_world.cwl` with `cwltool` passing an input parameter.
+
 $ cwltool hello_world.cwl --message="Hola mundo"
 INFO /home/kinow/Development/python/workspace/user_guide/venv/bin/cwltool 3.1.20220406080846
 INFO Resolved '/tmp/hello_world.cwl' to 'file:///tmp/hello_world.cwl'
@@ -86,7 +96,9 @@ Another way of passing values to your workflow input parameters is via an
 *Inputs Object*. This is a file containing the input fields with the
 corresponding values. This file can be written in JSON or YAML. For example:
 
-```json
+```{code-block} json
+:name: hello_world-jobjson
+:caption: hello_world-job.json
 {
   "message": "こんにちは世界"
 }
@@ -95,7 +107,9 @@ corresponding values. This file can be written in JSON or YAML. For example:
 
 You can use this Inputs Object file now to execute the “Hello World” workflow:
 
-```bash
+```{code-block} console
+:name: passing-an-inputs-object-file-to-cwltool
+:caption: Passing an Inputs Object file to `cwltool`.
 $ cwltool hello_world.cwl hello_world-job.json
 INFO /home/kinow/Development/python/workspace/user_guide/venv/bin/cwltool 3.1.20220406080846
 INFO Resolved '/tmp/hello_world.cwl' to 'file:///tmp/hello_world.cwl'
@@ -109,8 +123,9 @@ INFO Final process status is success
 
 ```{note}
 We used a similar file name for the workflow and for the inputs object files.
-It is not a requirement for CWL, but the *-job.json* suffix is very common.
-You can choose any name for your workflows and inputs object files.
+The *-job.json* suffix is very common in Inputs Object files, but it is not
+a requirement. You can choose any name for your workflows and inputs object
+files.
 ```
 
 ## Learn more