Spielend programmieren lernen

Programmierkurse für Kinder, Jugendliche und Erwachsene

User Tools

Site Tools



  • date 2013-07-14 21:06
  • author Horst JENS
  • tags ThePythonGameBook, code, learning
  • category english
  • slug 20130714_sphinx


Currently i am not only researching about Github pages but also about Sphinx a docutils tool to create  python documentation pages. The resulting output can be rendered in several formats ( html, pdf, man-page..) and the writing of the documentation is done by editing Restructured Text files.

The output looks very much like the official python documentation, with index, references, “next” and “previous” links etc.

I got the hint about looking into Sphinx at the Europython 2013 conference from a friend. 

So far i managed to include source code (not directly from Github, but from my local git folder) but without line numbers. I can force line numbers but i loose the pyglet syntax highlights so i let it be for now. 

At the moment i learn how to use links and cross-references. I don't care for most of the python-specific features of sphinx (auto-doctest etc) because i want to write a book with some code snippets, not big code with some documentation snippets.

Basically i can do most of the stuff i currently do with dokuwiki, some things (floating side boxes) even look better. pdf output is not very good yet (graphics overwritten by background color etc), but i never managed a good pdf output with dokuwiki either. That is not because of Dokuwiki can't do pdf, but because of my chaotic management of different dokuwiki plugins.

While i dislike the whole restructured-text markup language (compared to dokuwiki's markup syntax) i feel that with a  bit more learning i could be able to transfer ThePythonGameBook to Sphinx and publish the sphinx-generated html files directly with github pages, while managing the sphinx source files (.rst, images etc.) with github.

The question remains if this is a good idea.

/var/www/horst/spielend-programmieren.at/data/pages/en/blog/2013/0714_sphinx.txt · Last modified: 2017/10/12 09:43 (external edit)