Automating GIS-processes - Sphinx + GitHub Pages
Source documents for maintaining the Automating GIS-processes course pages.
The docs are written using a combination of Sphinx and Jupyter Notebooks. All the rst files for the lesson contents are located in source/lessons -folder and all notebooks are located in source/notebooks folder. Build html pages are located in a separate branch called gh-pages.
License and terms of usage
We hope that the materials provided here would be helpful for others. Thus, we share all the lesson materials openly, and also our source codes and lesson materials are openly available from these pages.
Our materials and code snippets are licensed with Creative Commons Attribution-ShareAlike 4.0 International licence and GNU GPLv3 license.
Read more about the license and terms of usage from here.
Docs are written using Sphinx with modified version of the Read The Docs theme. Google Analytics is used for tracking the usage of the site. Thus for building these pages with Sphinx you need to install following (we recommend installing conda from Anaconda Python distribution package):
conda install -c anaconda sphinx=1.5.1
Read The Docs Theme
conda install -c anaconda sphinx_rtd_theme=0.1.9
Google Analytics Sphinx plugin (exceptionally install with Pip that comes with Anaconda!)
pip install https://pypi.python.org/packages/48/7e/1b383d54276a743ee195f6f97a2a77054fa1f976913923e1e64fe500d975/sphinxcontrib-googleanalytics-0.1.tar.gz#md5=f9da59a753b8a045945c5e35ed1e2481
Writing .rst files
Sphinx uses .rst -files (reStucturedText). Thus all the documentation needs to be written into .rst files. It is easy, intuitive and quite similar to write as Markdown but rst makes it possible to include many things that are impossible to do with Markdown (such as including raw html code, embedding videos or interactive visualizations, having nice colored notes or hints etc.). All the .rst -files should be placed into the /source -folder which is the directory where Sphinx tries to find the documentation by default. Those .rst files are also the ones that you want to modify if you desire to make changes to the documents.
Writing Jupyter Notebook files
Continuous Integration with Travis CI
Travis-CI makes it possible to build the GitHub pages automatically whenever a change has been pushed to master.
It is highly recommendable to use separate branches for developing the materials (such as using
develop branch) and then merging the changes
from that branch to
master using pull requests.
- Travis Integration is controlled from .travis.yml.
- See a bit more documentation from Travis-integration.md
Browser based programming environment
This course site provides programming environment that allows anyone to immediately try and run all the codes directly in the browser. This functionality is done using Binder and CSC Notebooks (for Universities in Finland) -services.
Binder environment is controlled from environment.yml. CSC Notebooks are controlled separately from https://github.com/Automating-GIS-processes/notebooks -repository.
Contact & Developers
See contact info from here.