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 Europyhton 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.

please flattr: Flattr this


About Horst JENS

teaching open source game programming to kids
This entry was posted in python and tagged , , , . Bookmark the permalink.

One Response to Sphinx

  1. Pingback: goblins! | The Python Game Book Blog

Leave a Reply

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s