Merge pull request #25 from rl-institut/feature-4-gh-page-deploy

Publish documentation on GitHub Page

.github/workflows/gh-pages.yml

@@ -0,0 +1,21 @@
+name: gh-pages
+on:
+  push:
+    branches:
+      - production
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - uses: actions/cache@v2
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install --upgrade -r requirements.txt
+      - run: mkdocs gh-deploy --force

CHANGELOG.md

@@ -32,6 +32,7 @@ Template:
 - Add example code with google docstrings [(#20)](https://github.com/rl-institut/super-repo/pull/20)
 - Add `requirements.txt` for python environment dependencies [(#20)](https://github.com/rl-institut/super-repo/pull/20)
 - Add templates for issues and PR [(#15)](https://github.com/rl-institut/super-repo/pull/15)
+- Add a GitHub workflow to deploy documentation [(#25)](https://github.com/rl-institut/super-repo/pull/25)
 
 ### Changed
 - Update the .gitignore [(#19)](https://github.com/rl-institut/super-repo/pull/19)

README.rst

@@ -11,7 +11,7 @@ super-repo
    * - License
      - |badge_license|
    * - Documentation
-     - 
+     - |badge_documentation|
    * - Publication
      - 
    * - Development
@@ -32,10 +32,10 @@ Introduction
 
 Documentation
 =============
-Documentation is in `sphinx
-<http://www.sphinx-doc.org/en/stable/>`_ reStructuredText format 
-in the ``doc`` sub-folder of the repository.
-
+| The documentation is created with Markdown using `MkDocs <https://www.mkdocs.org/>`_.
+| All files are stored in the ``docs`` folder of the repository.
+| A **GitHub Actions** deploys the ``production`` branch on a **GitHub Page**.
+| The documentation page is `rl-institut.github.io/super-repo/ <https://rl-institut.github.io/super-repo/>`_
 
 Collaboration
 =============
@@ -54,6 +54,10 @@ License and Citation
     :target: LICENSE.txt
     :alt: License
 
+.. |badge_documentation| image:: https://img.shields.io/github/actions/workflow/status/rl-institut/super-repo/gh-pages.yml?branch=production
+    :target: \docs
+    :alt: Documentation
+
 .. |badge_contributing| image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat
     :alt: contributions
 
@@ -74,4 +78,3 @@ License and Citation
 
 .. |badge_pr_closes| image:: https://img.shields.io/github/issues-pr-closed-raw/rl-institut/super-repo
     :alt: closes issues
-

docs/documentation/index.md

@@ -10,14 +10,23 @@
 ## MkDocs
 
 ### Install
+Install the required packages. <br>
 `pip install mkdocs` install MkDocs <br>
-`pip install mkdocs-material` install the material theme <br>
+`pip install mkdocs-material` install the material theme
 
 ### Build
-`mkdocs serve` start the local live version of the documentation
-
-`mkdocs build` build the documentation
+Generate the documentation. <br>
+`mkdocs serve` start the local live version of the documentation <br>
+`mkdocs build` create a folder `site` with the documentation
 
 ### Publish
-Publish MkDocs project on github pages (requires permissions on repository) <br>
-`mkdocs gh-deploy` manually deploy the local docs files to github pages
+
+#### Manually
+Publish documentation on **GitHub Pages**. <br>
+`mkdocs gh-deploy` manually deploys the documentation files
+
+#### GitHub Action
+Deploy the documentation with **GitHub Actions**. <br>
+The file `.github\workflows\gh-pages.yml` creates an automated GitHub workflow. <br>
+It is configured to be pushed to the branch `gh-page` and then deployed online. <br>
+A commit on the `production` branch triggers the workflow.