Rendering reST on Windows
- Python: used by Sphinx
- Sphinx: main tool used to transform reST (.rst) into HTML or PDF
- TYPO3 templates: official TYPO3 templates for reST
notice - Note
- LaTeX: document preparation system used as intermediate format by Sphinx to generate prettier PDF out of reST files
notice - Note
Installing the Components
This tutorial is based on article .
Download the Python Windows Installer from http://www.python.org/download/releases/. The version we tested is Python 2.7, the 32 bit version ("Windows X86 MSI Installer") even we were on a 64-bit operating system as the setup tools seemed to have problem detecting our version of Python :(
Installing the Python Tools
Then download the Python Tools from http://pypi.python.org/pypi/setuptools#files (choose the .exe for Python 2.7) and execute it. The install wizard should install the Python tools smoothly (hopefully).
Set Environment variable by opening Control Panel > System > Advanced system parameters > Environment variables and add
and update PATH to read:
Of course you should change C:\Python27 to match the install directory you chose.
Installing graph tools
Download the current stable version of Graphviz from http://graphviz.org/Download_windows.php (at time of writing this was graphviz-2.28.0.msi). Then execute the msi file to install Graphviz.
Great, we're nearly done!
Open a command line (Start > All Programs > Accessories > Command Line) and execute the following commands:
C:\windows\System32> python --version Python 2.7.3 C:\windows\System32> easy_install pyyaml C:\windows\System32> easy_install sphinx C:\windows\System32> easy_install blockdiag C:\windows\System32> easy_install sphinxcontrib-blockdiag C:\windows\System32> easy_install seqdiag C:\windows\System32> easy_install sphinxcontrib-seqdiag C:\windows\System32> easy_install actdiag C:\windows\System32> easy_install sphinxcontrib-actdiag C:\windows\System32> easy_install nwdiag C:\windows\System32> easy_install sphinxcontrib-nwdiag
Installing TYPO3 Templates
The TYPO3 templates are available for the time being from a dedicated Git repository. If you did not yet configure your environment for using Git, please do so using one of the Git Tutorials.
The template projects is available from git://git.typo3.org/Documentation/RestTools.git. Clone that repository and move into it:
$ git clone git://git.typo3.org/Documentation/RestTools.git $ cd RestTools
Move down one more sub-folder and run the provided installer:
$ cd ./ExtendingSphinxForTYPO3 $ python setup.py install
This installs the TYPO3 Sphinx theme on your machine. Next time you will compile your documentation with
C:\> make html
you will have a nicer HTML documentation using the official TYPO3 template.
Install the full MiKTeX distribution from http://www.miktex.org/. Choose the "MiKTeX 2.9 Basic Installer", run the installer:
- Install package on the fly: Ask me first (or "Yes" as you want)
The first time you compile a PDF document from your reST documentation you will have to allow the download and installation of a few packages. Alternatively, you could choose to install a full-fledge version of MiKTeX (but it's a LOT bigger).
First Project with Sphinx
Please read our dedicated tutorial.