#29: Use sphinx for documentation #31

tkilias · 2021-06-10T17:38:55Z

This pull request integrates sphinx into our documentation and repository layout.
It enables us to deploy the documentation for all released versions on github pages to the branch github-pages/main
The existing documentation was transformed to restructuredText and will be build now with sphinx
Sphinx can also generate an API Documentation for us
Sphinx can check for broken links (not yet integrated)
Closes Add sphinx for documentation #29

…o add tasks to poetry.

…keep for _static and _templates directory

…-pages-current

… We need this provide the documentation for all available versions.

.github/workflows/check_github_pages_docs_for_current.yaml

.github/workflows/deploy_github_pages_docs_for_main.yaml

doc/conf.py

doc/deploy-to-github-pages-current.sh

doc/deploy-to-github-pages.sh

…es/root in deploy-to-github-pages.sh

doc/changes/changes_0.1.0.md

doc/deploy-to-github-pages.sh

…he developer guide

doc/changes/changes_0.1.0.md

doc/developer_guide/building_documentation.rst

Co-authored-by: Thomas Ubensee <34603111+tomuben@users.noreply.github.com>

tkilias added 21 commits March 23, 2021 20:45

First test to use sphinx for documentation

0fe4d5c

Properly setup sphinx and transformed README to rst. Use poethepoet t…

6921bb6

…o add tasks to poetry.

Test rst references

4ba663f

Add deployment script for the documentation to github pages. Add .git…

d8b4cd7

…keep for _static and _templates directory

Add deployment scripts for sphinx documentation

441006e

Update poetry version in CI

9f201f3

Add poetry install to install packages

bc66fc0

Ignore github-pages/* branches

4c2665d

Remove markdown residuals from README

1a0e039

add git fetch into github_pages_docs* CI scripts

70f6719

Remove ref to user guide from README

05ee4d0

Test checkout in CI if it is sufficient for commit-html-doc-to-github…

86df39d

…-pages-current

Remove empty headlines from README

9674a58

debug github CI github_pages_docs_for_current.yaml

3f40cfa

debug github CI github_pages_docs_for_current.yaml

1c4675e

debug github CI github_pages_docs_for_current.yaml

bd3494f

debug github CI github_pages_docs_for_current.yaml

8644311

Use workaround to set new github-pages branch to the correct commit id

f879efc

debug github CI github_pages_docs_for_current.yaml

5ff0532

Fix structure of sphinx docu and start with content conversion

fdc7813

Allow multiple versions of the documentation live in the same branch.…

c157eea

… We need this provide the documentation for all available versions.

tkilias requested a review from tomuben June 10, 2021 17:38

Move git user config before the git commit for the deployment

af8859e

tomuben reviewed Jun 10, 2021

View reviewed changes

.github/workflows/check_github_pages_docs_for_current.yaml Outdated Show resolved Hide resolved

tomuben reviewed Jun 10, 2021

View reviewed changes

.github/workflows/deploy_github_pages_docs_for_main.yaml Outdated Show resolved Hide resolved

tomuben reviewed Jun 10, 2021

View reviewed changes

doc/conf.py Show resolved Hide resolved

tomuben reviewed Jun 10, 2021

View reviewed changes

doc/deploy-to-github-pages-current.sh Outdated Show resolved Hide resolved

tomuben reviewed Jun 10, 2021

View reviewed changes

doc/deploy-to-github-pages.sh Outdated Show resolved Hide resolved

tomuben reviewed Jun 10, 2021

View reviewed changes

doc/deploy-to-github-pages.sh Outdated Show resolved Hide resolved

tomuben reviewed Jun 10, 2021

View reviewed changes

doc/deploy-to-github-pages.sh Outdated Show resolved Hide resolved

tomuben reviewed Jun 22, 2021

View reviewed changes

doc/deploy-to-github-pages.sh Show resolved Hide resolved

GitHub Action added 2 commits June 22, 2021 17:36

Add explanation for default branches github-pages/main and github-pag…

e3d4f7e

…es/root in deploy-to-github-pages.sh

Add issue to changes_0.1.0.md and fix missing empty line

0a5d27f

tkilias requested a review from tomuben June 22, 2021 17:28

tomuben reviewed Jun 22, 2021

View reviewed changes

doc/changes/changes_0.1.0.md Outdated Show resolved Hide resolved

tomuben reviewed Jun 22, 2021

View reviewed changes

doc/deploy-to-github-pages.sh Outdated Show resolved Hide resolved

tomuben reviewed Jun 22, 2021

View reviewed changes

doc/deploy-to-github-pages.sh Outdated Show resolved Hide resolved

tkilias and others added 4 commits June 23, 2021 11:48

Apply suggestions from code review

038de81

Add the creation of the new root commit to doc/deploy-to-github-pages.sh

99ebd60

Adding intitial eplaination about how to build the documentation to t…

d46a9ad

…he developer guide

Move git config user to the beginning in doc/deploy-to-github-pages.sh

8096638

tkilias requested a review from tomuben June 24, 2021 10:24