Translations
Info
All page names need to be in English.
en da  de  fr  it  ja  km  nl  ru  zh

Rendering reST on Linux

From TYPO3Wiki
Jump to: navigation, search

We use Sphinx as a tool-chain to generate TYPO3 documentation with reStructuredText (commonly abbreviated as reST).

Requirements

  • 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

These three components may be automatically installed and configured for you if you use the TYPO3 extension sphinx available in TER.

Optional components:

  • LaTeX: document preparation system used as intermediate format by Sphinx to generate prettier PDF out of reST files

notice - Note

The documentation of the Sphinx extension comes with a dedicated chapter for rendering PDF with LaTeX.

Installing the Components

Installing Python

Python should already be installed. To check this, open a console/terminal and type

$ python

You should see something like

Python 2.6.8 (unknown, Apr 19 2012, 01:24:00) 
[GCC 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2335.15.00)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>

Then quit as usual with ^D (ctrl+D).

The setup for the TYPO3 documentation requires the use of YAML. Thus you need to install the Python YAML module. To check installed module:

$ python
>>> help('modules')

The simplest way to install that module is to use "easy_install". On Debian, easy_install is provided by package 'python-pip'

$ (sudo) easy_install pyyaml

Installing Sphinx

Hereafter we describe the process to install Sphinx as a stable version or from a development snapshot.

Stable Version

Sphinx may be available in the ports of your system. Best is to check this first.

MacOS X with MacPorts:

$ sudo port install py-sphinx
$ sudo port select sphinx py27-sphinx

Debian Linux:

At the time of writing, installing Sphinx with:

$ sudo apt-get install python-sphinx

provides an old version of Sphinx (0.6.x) that does not support gettext (JSON) extraction. So we suggest you install it with:

$ sudo apt-get install python-setuptools
$ easy_install -U Sphinx

If your operating system does not provide such packages or typically if you are using MacOS without MacPorts, you may install Sphinx from the Python Package Index with:

$ easy_install -U Sphinx


Mageia Linux:

$ sudo urpmi python-sphinx

Development Version

DISCLAIMER: You really should consider using an official stable distribution unless you know that you need the bleeding edge version of Sphinx.

You can download a snapshot from the Mercurial development repository:

Alternatively, you may clone the development repository with:

$ hg clone https://bitbucket.org/birkenfeld/sphinx

Then compile and install:

$ python setup.py build
$ sudo python setup.py install

Installing the TypoScript lexer

Syntax highlighting is performed using Pygments. A dedicated TypoScript lexer exists and is used to perform syntax highlighting on TS blocks in the documentation.

To install the lexer, do the following:

1) get the lexer from: https://git.typo3.org/Documentation/RestTools.git/blob_plain/HEAD:/ExtendingPygmentsForTYPO3/_incoming/typoscript.py and copy it to wherever the Pygments lexer are located on your machine.

$ wget https://git.typo3.org/Documentation/RestTools.git/blob_plain/HEAD:/ExtendingPygmentsForTYPO3/_incoming/typoscript.py

2) move to that directory and update the list of available lexers by running:

$ (sudo) python _mapping.py

Note: on Mac OS X, the lexers are found in "/Library/Python/(version number)/site-packages/Pygments-(some other version number).egg/pygments/lexers/"

Note: on Mageia Linux the lexers are found in "/usr/lib/python(version number)/site-packages/pygments/lexers/"

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
$ (sudo) python setup.py install

This installs the TYPO3 Sphinx theme on your machine. Next time you will compile your documentation with

$ make html

you will have a nicer HTML documentation using the official TYPO3 template.

First Project with Sphinx

Please read our dedicated tutorial.

Troubleshooting

The setup may not go as smoothly as described above. Here are some tips that will hopefully be useful.

Mac OS X and MacPorts: conflicting Python installs

(Francois (talk) 21:03, 5 July 2012 (CEST)) I encountered problems when trying to install Sphinx via MacPorts. MacPorts installed Python too, because it was a dependency of Sphinx, so you end up with several versions of Python installed (since OS X ships with one already). Running "sphinx-build" obviously called the "python" interpreter from OS X and not from MacPorts causing errors like:

sphinx-build -b html -d build/doctrees  -c . -a -E -w ./_not_versioned/warnings.txt .. build/html
Traceback (most recent call last):
  File "/opt/local/bin/sphinx-build", line 5, in ?
    from pkg_resources import load_entry_point
  File "/opt/local/lib/python2.4/site-packages/pkg_resources.py", line 2735, in ?
    working_set.require(__requires__)
  File "/opt/local/lib/python2.4/site-packages/pkg_resources.py", line 690, in require
    needed = self.resolve(parse_requirements(requirements))
  File "/opt/local/lib/python2.4/site-packages/pkg_resources.py", line 588, in resolve
    raise DistributionNotFound(req)
pkg_resources.DistributionNotFound: uuid>=1.30
make: *** [html] Error 1

Installing Sphinx using "easy_install" instead solved this issue.

Missing default locale

On some systems (the problem is reported in particular on Mac OS X Lion and Ubuntu), Python will complain about an invalid locale. The error trace ends with something like:

  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 496, in getdefaultlocale
    return _parse_localename(localename)
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/locale.py", line 428, in _parse_localename
    raise ValueError, 'unknown locale: %s' % localename
ValueError: unknown locale: UTF-8
make: *** [html] Error 1

In such a case, it is necessary to define the default locale by using:

export LANG="en_US.UTF-8"
export LC_ALL="en_US.UTF-8"

The exact syntax will depend on the shell you use. You should set these command in your profile to avoid having to type them every time.

Reference: https://code.djangoproject.com/ticket/16017