Fine tuning documentation pages.

doc/JobTemplate/Documentation/LaTeXDocumentation.rst

@@ -3,9 +3,11 @@
 LatexDocumentation
 ##################
 
-The ``LatexDocumentation`` job template ................
+The ``LatexDocumentation`` job template downloads an artifact containing a LaTeX document and translates to a PDF file
+using MikTeX.
 
-* uses xelatex and latexmk
+The translation process uses ``latexmk`` for handling multiple passes. The default LaTeX processor is ``xelatex``, but
+can be switched by a parameter.
 
 .. topic:: Features
 
@@ -13,12 +15,9 @@ The ``LatexDocumentation`` job template ................
 
 .. topic:: Behavior
 
-   .. todo:: LatexDocumentation:Behavior needs documentation.
-
-.. topic:: Job Execution
-
-   .. image:: ../../_static/pyTooling-Actions-LatexDocumentation.png
-      :width: 600px
+   1. Download the LaTeX artifact.
+   2. Build the PDF using ``latexmk``.
+   3. Upload the generated PDF as an artifact.
 
 .. topic:: Dependencies
 
@@ -40,9 +39,6 @@ The ``LatexDocumentation`` job template ................
 Instantiation
 *************
 
-The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. It only
-requires a `name` parameter to create the artifact names.
-
 .. code-block:: yaml
 
    name: Pipeline
@@ -77,11 +73,6 @@ requires a `name` parameter to create the artifact names.
          pdf_artifact:   ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_pdf }}
 
 
-.. seealso::
-
-   :ref:`JOBTMPL/TagReleaseCommit`
-     ``LatexDocumentation`` is usualy
-
 .. _JOBTMPL/LatexDocumentation/Parameters:
 
 Parameter Summary

doc/JobTemplate/Documentation/PublishToGitHubPages.rst

@@ -0,0 +1,106 @@
+.. _JOBTMPL/PublishToGitHubPages:
+
+PublishToGitHubPages
+####################
+
+This job publishes HTML content from artifacts of other jobs to GitHub Pages.
+
+**Behavior:**
+
+1. Checkout repository.
+2. Download artifacts.
+3. Push HTML files to branch ``gh-pages``.
+
+**Dependencies:**
+
+* :gh:`actions/checkout`
+* :gh:`actions/download-artifact`
+
+Instantiation
+*************
+
+Simple Example
+==============
+
+.. code-block:: yaml
+
+   jobs:
+     BuildTheDocs:
+       # ...
+
+     PublishToGitHubPages:
+       uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r5
+       needs:
+         - BuildTheDocs
+       with:
+         doc: Documentation
+
+
+Complex Example
+===============
+
+.. code-block:: yaml
+
+   jobs:
+     PublishToGitHubPages:
+       uses: pyTooling/Actions/.github/workflows/PublishToGitHubPages.yml@r5
+       needs:
+         - Params
+         - BuildTheDocs
+         - Coverage
+         - StaticTypeCheck
+       with:
+         doc: ${{ fromJson(needs.Params.outputs.artifact_names).documentation_html }}
+         coverage: ${{ fromJson(needs.Params.outputs.artifact_names).codecoverage_html }}
+         typing: ${{ fromJson(needs.Params.outputs.artifact_names).statictyping_html }}
+
+
+Parameters
+**********
+
+doc
+===
+
++----------------+----------+----------+--------------+
+| Parameter Name | Required | Type     | Default      |
++================+==========+==========+==============+
+| doc            | yes      | string   | — — — —      |
++----------------+----------+----------+--------------+
+
+Name of the documentation artifact.
+
+
+coverage
+========
+
++----------------+----------+----------+-----------------+
+| Parameter Name | Required | Type     | Default         |
++================+==========+==========+=================+
+| coverage       | optional | string   | ``""``          |
++----------------+----------+----------+-----------------+
+
+Name of the coverage artifact.
+
+
+typing
+======
+
++----------------+----------+----------+-----------------+
+| Parameter Name | Required | Type     | Default         |
++================+==========+==========+=================+
+| typing         | optional | string   | ``""``          |
++----------------+----------+----------+-----------------+
+
+Name of the typing artifact.
+
+
+
+Secrets
+*******
+
+This job template needs no secrets.
+
+Results
+*******
+
+This job template has no output parameters.

doc/JobTemplate/Documentation/SphinxDocumentation.rst

@@ -3,7 +3,8 @@
 SphinxDocumentation
 ###################
 
-The ``SphinxDocumentation`` job template ..........
+The ``SphinxDocumentation`` job template compiles the ReStructured Text documentation using Sphinx to an HTML website
+and a LaTeX documentation. This LaTeX document can be translated using e.g. MikTeX to a PDF file.
 
 .. topic:: Features
 
@@ -20,7 +21,17 @@ The ``SphinxDocumentation`` job template ..........
 
 .. topic:: Behavior
 
-   .. todo:: SphinxDocumentation:Behavior needs documentation.
+   1. Checkout repository.
+   2. Install system dependencies.
+   3. Setup Python environment and install Python dependencies.
+   4. Download optional artifacts for integration of futher reports into the documentation.
+   5. Build the HTML documentation using Sphinx.
+   6. Build the LaTeX documentation using Sphinx.
+
+      1. Apply LaTeX workaround I.
+      2. Apply LaTeX workaround II.
+
+   7. Upload the HTML and LaTeX artifacts.
 
 .. topic:: Job Execution
 
@@ -54,9 +65,6 @@ The ``SphinxDocumentation`` job template ..........
 Instantiation
 *************
 
-The following instantiation example creates a ``Params`` job derived from job template ``Parameters`` version ``@r5``. It only
-requires a `name` parameter to create the artifact names.
-
 .. code-block:: yaml
 
    name: Pipeline
@@ -81,11 +89,6 @@ requires a `name` parameter to create the artifact names.
          latex_artifact: ${{ fromJson(needs.UnitTestingParams.outputs.artifact_names).documentation_latex }}
 
 
-.. seealso::
-
-   :ref:`JOBTMPL/TagReleaseCommit`
-     ``SphinxDocumentation`` is usualy
-
 .. _JOBTMPL/SphinxDocumentation/Parameters:
 
 Parameter Summary

doc/JobTemplate/Documentation/VerifyDocs.rst

@@ -1,42 +0,0 @@
-.. _JOBTMPL/VerifyDocs:
-
-VerifyDocs
-##########
-
-This job extracts code examples from the README and tests these code snippets.
-
-**Behavior:**
-
-TBD
-
-**Dependencies:**
-
-TBD
-
-Instantiation
-*************
-
-Simple Example
-==============
-
-.. todo:: VerifyDocs:SimpleExample Needs documentation.
-
-Complex Example
-===============
-
-.. todo:: VerifyDocs:ComplexExample Needs documentation.
-
-Parameters
-**********
-
-.. todo:: VerifyDocs:Parameters Needs documentation.
-
-Secrets
-*******
-
-This job template needs no secrets.
-
-Results
-*******
-
-This job template has no output parameters.

doc/JobTemplate/Documentation/index.rst

@@ -5,13 +5,13 @@ Documentation
 
 The category *documentation* provides workflow templates implementing
 
-* :ref:`JOBTMPL/VerifyDocs` -
-* :ref:`JOBTMPL/SphinxDocumentation` -
-* :ref:`JOBTMPL/LaTeXDocumentation` -
+* :ref:`JOBTMPL/SphinxDocumentation` - Translate ReStructured Text to HTML and LaTeX using Sphinx.
+* :ref:`JOBTMPL/LaTeXDocumentation` - Translate LaTeX to PDF using MikTeX.
+* :ref:`JOBTMPL/PublishToGitHubPages` - Upload HTML content to GitHub Pages.
 
 .. toctree::
    :hidden:
 
-   VerifyDocs
    SphinxDocumentation
    LaTeXDocumentation
+   PublishToGitHubPages