Automating GIS-processes - Sphinx + GitHub Pages

Source documents for maintaining the Automating GIS-processes course pages, year 2017.

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 the docs -folder.

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.

Requirements

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):

• Sphinx

  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.

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.

Building the pages manually with sphinx

Unlike Markdown pages (such as this page), Sphinx pages need to be build before you can see the final result. This is because Sphinx produces html pages (into /docs -folder) that can have many nice features such as the navigation bar on the left, efficient search functionality etc.

Build the pages by navigating to the root of the repository (i.e. to a folder where this README.md -file is located) and executing following command:

make html

Sphinx will then start building the pages and the final html pages will be located in /docs -folder. This is a custom location (by default the docs would go to /build -folder) that matches how GitHub wants them so that GitHub Pages works. I have edited the make.bat for achieving this.

Sphinx actually runs the codes!

One of the most powerful features that Sphinx has (in my opinion), is that it will actually run all the Python codes that are written under the .. ipython:: python code block. This makes it possible that you can e.g. plot images dynamically to the pages without doing any manual work (adding images with links), see and show the contents of a datafile on the pages without needing to add them manually (which is how you would do it on Markdown pages). Hence, doing the documentation reminds a bit how you can write documents with Jupyter Notebooks but with a nicer looking pages.

Data needs to be in the repository

What this kind of dynamic Python interpreter of Sphinx means though, is that you need to also keep the data that you use in the documentation together with the docs. I keep all the datasets used for building these pages in the /data -folder and then read the files from there in the background (hidden from the user). See an example of how to hide (with :suppress: command) the data-reading-procedure from the user, from here.

Contact & Developers

• Henrikki Tenkanen

• Vuokko Heikinheimo.

See contact info from here.