We presume your wiki is located on the server at:
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 http://bitbucket.org/kevindunn/sphinx-wiki
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
sphinx-wiki.py 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
6. Add the following line to your wiki's
License, copyright, and assistance
This extension is licensed under the new 3-clause BSD license. Copyright is held by Kevin Dunn, firstname.lastname@example.org, 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
<rst> ... </rst> tags in the wiki. We will call that text the
rst_text in these instructions.
rst_text is received by
sphinx-wiki.py, 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> <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. </rst>
The default for both options is
`True`, so you can omit both options, if
'toc' option will generate a table of contents at the start of your page,
using whatever table of contents that Sphinx would have generated.
'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.