From afb7df443f680215a99c57810c2d1888c61fbadb Mon Sep 17 00:00:00 2001 From: Ludee Date: Mon, 20 Feb 2023 15:25:46 +0100 Subject: [PATCH 1/8] Update documentation for gh-page #4 --- docs/documentation/index.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/documentation/index.md b/docs/documentation/index.md index f0ca7e6..03901d3 100644 --- a/docs/documentation/index.md +++ b/docs/documentation/index.md @@ -19,5 +19,10 @@ `mkdocs build` build the documentation ### Publish -Publish MkDocs project on github pages (requires permissions on repository)
+Publish MkDocs project on **GitHub Pages** (requires permissions on repository)
`mkdocs gh-deploy` manually deploy the local docs files to github pages + +Deploy with **GitHub Actions** +The file `.github\workflows\gh-pages.yml` creates an automated GitHub workflow. +It is configured that it is pushed to the branch `gh-page` and then deployed online. +A commit on the `production` branch triggers the workflow. From 9030d4b7813bd056ff41e37040de9fcd3a6266c7 Mon Sep 17 00:00:00 2001 From: Ludee Date: Mon, 20 Feb 2023 15:26:26 +0100 Subject: [PATCH 2/8] Add action to deploy documentation #4 --- .github/workflows/gh-pages.yml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 .github/workflows/gh-pages.yml diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 0000000..7ffe8ef --- /dev/null +++ b/.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 From 12762f58b3f96b2a1e52575b1b74b62daef77249 Mon Sep 17 00:00:00 2001 From: Ludee Date: Mon, 20 Feb 2023 15:27:15 +0100 Subject: [PATCH 3/8] Add placeholder for documentation badge #4 --- README.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 251fd24..7d19e3f 100644 --- a/README.rst +++ b/README.rst @@ -11,7 +11,7 @@ super-repo * - License - |badge_license| * - Documentation - - + - |badge_documentation| * - Publication - * - Development @@ -54,6 +54,8 @@ License and Citation :target: LICENSE.txt :alt: License +.. |badge_documentation| ToDo! + .. |badge_contributing| image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat :alt: contributions From 22378c8a4ac3748e7d4343c7f44ef995610a9901 Mon Sep 17 00:00:00 2001 From: Ludee Date: Mon, 20 Feb 2023 20:43:42 +0100 Subject: [PATCH 4/8] Update documenation for GitHub Page workflow #4 --- docs/documentation/index.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/documentation/index.md b/docs/documentation/index.md index 03901d3..3f394df 100644 --- a/docs/documentation/index.md +++ b/docs/documentation/index.md @@ -10,19 +10,23 @@ ## MkDocs ### Install +Install the required packages.
`pip install mkdocs` install MkDocs
-`pip install mkdocs-material` install the material theme
+`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.
+`mkdocs serve` start the local live version of the documentation
+`mkdocs build` create a folder `site` with the documentation ### Publish -Publish MkDocs project on **GitHub Pages** (requires permissions on repository)
-`mkdocs gh-deploy` manually deploy the local docs files to github pages -Deploy with **GitHub Actions** -The file `.github\workflows\gh-pages.yml` creates an automated GitHub workflow. -It is configured that it is pushed to the branch `gh-page` and then deployed online. +#### Manually +Publish documentation on **GitHub Pages**.
+`mkdocs gh-deploy` manually deploys the documentation files + +#### GitHub Action +Deploy the documentation with **GitHub Actions**.
+The file `.github\workflows\gh-pages.yml` creates an automated GitHub workflow.
+It is configured to be pushed to the branch `gh-page` and then deployed online.
A commit on the `production` branch triggers the workflow. From 0f3cc64ffe98517e173d94df97258bc21cbece9b Mon Sep 17 00:00:00 2001 From: Ludee Date: Mon, 20 Feb 2023 20:59:49 +0100 Subject: [PATCH 5/8] Update docs badge #4 --- README.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 7d19e3f..9900198 100644 --- a/README.rst +++ b/README.rst @@ -54,7 +54,9 @@ License and Citation :target: LICENSE.txt :alt: License -.. |badge_documentation| ToDo! +.. |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 @@ -76,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 - From 9f8c462a3c3957856e0e36a2c611a2d441520ef5 Mon Sep 17 00:00:00 2001 From: Ludee Date: Mon, 20 Feb 2023 21:12:10 +0100 Subject: [PATCH 6/8] Update README text and link #4 --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 9900198..527f861 100644 --- a/README.rst +++ b/README.rst @@ -32,10 +32,10 @@ Introduction Documentation ============= -Documentation is in `sphinx -`_ reStructuredText format -in the ``doc`` sub-folder of the repository. - +The documentation is created with Markdown using `MkDocs `_.
+All files are stored in the ``docs`` folder of the repository.
+A **GitHub Actions** deploys the ``production`` branch on a **GitHub Page**.
+The page is `rl-institut.github.io/super-repo/ `_ Collaboration ============= From 0b012dfe6e5a3850b95f9de9364534965f447575 Mon Sep 17 00:00:00 2001 From: Ludee Date: Mon, 20 Feb 2023 21:13:59 +0100 Subject: [PATCH 7/8] Fix rst syntax #4 --- README.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.rst b/README.rst index 527f861..a23965a 100644 --- a/README.rst +++ b/README.rst @@ -32,10 +32,10 @@ Introduction Documentation ============= -The documentation is created with Markdown using `MkDocs `_.
-All files are stored in the ``docs`` folder of the repository.
-A **GitHub Actions** deploys the ``production`` branch on a **GitHub Page**.
-The page is `rl-institut.github.io/super-repo/ `_ +| The documentation is created with Markdown using `MkDocs `_. +| 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/ `_ Collaboration ============= From 3f9c34c4769c3814c81f39d82c3fdc5a7338b31b Mon Sep 17 00:00:00 2001 From: Ludee Date: Mon, 20 Feb 2023 21:18:43 +0100 Subject: [PATCH 8/8] Update changelog #4 --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 97922c6..3fe8193 100644 --- a/CHANGELOG.md +++ b/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)