Clone wiki

sphinx-wiki / Home


We presume your wiki is located on the server at: /var/www/wiki

1. Create a directory for this extension:

        mkdir -p /var/www/wiki/extensions/sphinx-wiki

2. Clone the source code into this extension directory:

        cd /var/www/wiki/extensions/
        hg clone

Ensure this directory and all subdirectories below it are writable by your webserver.

3. Install the Python library wikitools that interacts with Mediawiki

        easy_install -U wikitools

4. Change the settings in the file to match your server settings and preferences. Your settings are likely OK if you can run this at the command line without any errors showing up. It should just "hang"; push Ctrl-C to quit it.


NOTE: you must be able to run the file as shown above, since that is what the PHP code will use to call this file. If you get an error message, try changing the very first line of this file to point to your Python 2.5 (or higher) executable.

5. Also adjust the setting in sphinx-wiki.php to point to the file.

6. Add the following line to your wiki's LocalSettings.php file:


This extension is licensed under the new 3-clause BSD license. Copyright is held by Kevin Dunn,, 2010. Please email the author for assistance, or file a bug here.


This extension is used on several sites operated by the author. Two that are publicly available as university courses:

On both sites you can click Edit at the top of the page to see the page's source.

Principle of operation

Mediawiki operates by converting your usual wiki markup to HTML.

The 2 files that make this wiki extension operate by intercepting any text that appears between <rst> ... </rst> tags in the wiki. We will call that text the rst_text in these instructions.

This rst_text is received by, and sent to Sphinx to be converted to HTML via Sphinx's pickle builder. That HTML is returned back to Mediawiki to display.

Special handling is required for images. Any images used in your code are assumed to have been uploaded to the wiki with the same name as used in the rst_text. Sphinx obviously requires to see your images when compiling your rst_text. So this code extracts the images from your wiki and makes them available to Sphinx.

After compiling, the code moves the images to a location on your server.

Cases when this code might not work for you

  • You need to cross reference to another part of some RST text in another wiki page.
  • You want to include other reStructuredText from another file using the .. include:: directive. This can be done with the current extension, in a non-standard manner - please email the extension maintainer.

How to use this extension

Just include the parts you want to be generated by Sphinx between <rst> ... </rst> tags in your wiki. Let the wiki take care of version control and collaborative editing as usual.

There are two options currently available to modify the extensions behaviour, shown by example:

    <rst-options: 'toc' = False/>
    <rst-options: 'reset-figures' = False/>

    Your RST code here, etc.

    Images must be included as:

    .. figure:: reactor.png
	    :scale: 40
	    :align: center

    This implies that an image, with the name "reactor.png" must be uploaded
    into the Mediawiki.


The default for both options is `True`, so you can omit both options, if not required.

The 'toc' option will generate a table of contents at the start of your page, using whatever table of contents that Sphinx would have generated.

The 'reset-figures' option can normally be set to False for most circumstances. If you set it to True, it will download the image from the wiki, using the wiki API. This can take quite some time, if there are many images in the page. So only change it to True if you've uploaded a new version of the image but kept the same image name.