The source files in this repository are used to build documentation for OneGeology users and service providers which is published to https://onegeology.github.io/documentation/.
Source files are written in reStructuredText and built into HTML pages using the Sphinx documentation generator with the Read the Docs theme.
Some of the reStructuredText was converted from pre-existing HTML files using pandoc as below:
pandoc --extract-media=appendixb -s -t rst https://onegeology.org/wmsCookbook/appendixB.html -o appendixb.rst
If you have Docker installed you can use the example Dockerfile.sphinx to build the documentation locally.
# To build the container
docker build -f Dockerfile.sphinx -t sphinxrtd .
# To build the documentation using the built container
cd docs
docker run --rm -v $PWD:/docs sphinxrtd make html
Otherwise you should follow the Sphinx documentation to set up a local build system and then add the sphinx_rtd_theme.
The source reStructuredText files are transformed using Sphinx via Gitub Actions CI/CD to web pages hosted on GitHub pages. When changes are merged into the master branch the GitHub Actions configured in .github/workflows/gh-pages.yml create the content of the gh-pages branch.
- follow Sphinx quickstart
- save to GitHub repo
- edit repo settings to enable GitHub pages from gh-pages branch.
- Create .github/workflows/gh-pages.yml
- Create SSH keys in Linux/Putty
- In repo settings>deploy add a=deply key such as "ghpagesdk" and copy/paste public key hash
- In repo settings>secrets add a secret key with same name "ghpagesdk" and copy/paste private key hash.
- make a commit to the master brach and should all be working.