During the Zurich QGIS hackfest we had some extended discussions about migrating our documentation away from LaTeX to sphinx because the latter offers a more approachable syntax for casual documentation writers and has good support for internationalisation via gettext. This week I am going to our first 2012 QGIS hackfest (to be held in Lyon,... Read more »
During the Zurich QGIS hackfest we had some extended discussions about migrating our documentation away from LaTeX to sphinx because the latter offers a more approachable syntax for casual documentation writers and has good support for internationalisation via gettext. This week I am going to our first 2012 QGIS hackfest (to be held in Lyon, France) and we will be spending some time and effort to move forward with the migration to sphinx. In order to get familiar with sphinx, I have slowly been moving my own documentation work from txt2tags (which I love for its simplicity, but it is not great for complex documents that need interdocument references) to sphinx (which is a little more complex but has many more bells and whistles). Sphinx provides a number of themes 'out of the box' for generated html content, but I don't really like any of them much and I want my stuff to look a little more unique. So I have dipped my toes a little into the waters of sphinx theme creation. This weekend I decided to make my efforts public. There are still a number of layout issues I want to address (mainly in the TOC sidebar), and I want to add some more explicit markup for various sphinx constructs, but what I have is already usable and hopefully interesting for others to try out. Here is a little screenshot of what the theme looks like:
You can download the theme from its github project page (https://github.com/timlinux/linfiniti-sphinx-theme) - the accompanying README should give you enough info to get started with it. I am hoping that we can use a variant of this theme for the QGIS project documentation too. I look forward to any patches to make the theme better any of you html/css gurus out there may have to offer!
This post summarizes how to install sphinx on Windows to contribute to PyQGIS Cookbook. I’m writing this as I go, so this most likely won’t be perfect.
I used my Python 2.6 stand-alone installation (not the one in OSGeo4W).
- Get the Sphinx egg from http://pypi.python.org/pypi/Sphinx
- If you don’t have it, install setuptools to get the easy_install script http://pypi.python.org/pypi/setuptools
- In C:\Python26\Scripts run
easy_install -U sphinx
- Get the PyQGIS source from https://github.com/qgis/QGIS-Developer-Cookbook
- Create a build folder inside the QGIS-Developer-Cookbook
- Now you can build the Cookbook:
sphinx-build "C:\Users\Anita\QGIS\QGIS-Developer-Cookbook\source" "C:\Users\Anita\QGIS\QGIS-Developer-Cookbook\build"
The build folder should now contain the Cookbook .html files.