Jan 26, 2015 Tags: Sphinx, T3Docs, Howto, Python

Sphinx-Doc Installation Steps

This post is about how to install the Sphinx documentation tools on your machine and how to get going with the first steps. Having done this you can render TYPO3 documentation projects at the commandline. For Linux, Mac and Windows. This post will be updated as needed.

Attention: I need your feedback: Martin Bless @ typo3.org

Thank you for feedback:

Updated on Aug 02, 2016

Navigate this page:

Quickstart for the impatient

Install Everything

Requirements: You need Python 2.6 or better, 2.7 for this and Pip.

With Sudo

Run these commands to install everything:

sudo pip install --upgrade pip
sudo pip install --upgrade sphinx
sudo pip install --upgrade pyyaml
sudo pip install --upgrade t3SphinxThemeRtd
sudo pip install --upgrade t3fieldlisttable
sudo pip install --upgrade t3tablerows
sudo pip install --upgrade t3targets
sudo pip install --upgrade sphinxcontrib-googlechart
sudo pip install --upgrade sphinxcontrib-googlemaps
sudo pip install --upgrade sphinxcontrib-httpdomain
sudo pip install --upgrade sphinxcontrib-slide
sudo pip install --upgrade sphinxcontrib.youtube

# # nice to have:
# sudo pip install --upgrade pillow

# end.

Without Sudo

Run these commands to install everything if sudo is not required:

pip install --upgrade pip
pip install --upgrade sphinx
pip install --upgrade pyyaml
pip install --upgrade t3SphinxThemeRtd
pip install --upgrade t3fieldlisttable
pip install --upgrade t3tablerows
pip install --upgrade t3targets
pip install --upgrade sphinxcontrib-googlechart
pip install --upgrade sphinxcontrib-googlemaps
pip install --upgrade sphinxcontrib-httpdomain
pip install --upgrade sphinxcontrib-slide
pip install --upgrade sphinxcontrib.youtube

# nice to have:
pip install --upgrade pillow

# end.

Render Documentation with the new Theme

TYPO3 documentation follows this convention:

path/to/PROJECT
path/to/PROJECT/Documentation
path/to/PROJECT/Documentation/Index.rst

To render the documentation of such a project download this ‘_make’ folder to:

path/to/PROJECT/Documentation/_make

Afterwards you can directly render the documentation:

cd ./path/to/PROJECT/Documentation/_make
make html
make singlehtml
make

Open the result in the webbrowser:

firefox path/to/PROJECT/Documentation/_make/build/html/Index.html
firefox path/to/PROJECT/Documentation/_make/build/singlehtml/Index.html

The Installation Steps In Detail

For Linux, Mac, Windows

  1. Test for Python

    Make sure Python 2 is available.

    Do this test:

    Type ‘python –version’ at the commandline:

    $ python --version
    

    Example of success:

    $ python --version
    Python 2.7.6
    

    Good.

    Go to next step.

    Example of failure:

    $ python --version
    Command not found
    

    Bad.

    Install Python for Linux, Mac, Windows.

    Read more.
  2. Test for PIP

    Make sure the Python packet manager PIP is available.

    Run this test:

    Type ‘pip’ at the command line:

    $ pip
    

    Example for success:

    $ pip
    Usage:
       pip <command> [options]
    ...
    Usage information is being printed.
    

    Example for failure:

    $ pip
    Command not found
    

    Good.

    Skip next step.

    Bad.

    Go to next step.

  3. Install PIP

    Install the Python Packet Manager PIP

    Do this:

    1. Download this file (rightclick and save as):

      get-pip.py.

      Or:

      $ wget https://bootstrap.pypa.io/get-pip.py
      
    2. Run as administrator:

      $ sudo python get-pip.py
      

    Read more.

  4. Install general Python Packages

    Install general Python packages
    sphinx

    The Sphinx documentation tools

    Run:

    $ sudo pip install --upgrade sphinx
    

    Dependencies will be resolved and several other packages will be installed. Read more.

    mandatory
    yaml

    Yaml support

    Run:

    $ sudo pip install --upgrade pyyaml
    

    Read more.

    necessary for older TYPO3 projects that still have a Settings.yml file instead of Settings.cfg which is the standard nowadays
    pillow

    Python imaging library

    Provide prerequisites:

    Run:

    $ sudo pip install --upgrade Pillow
    

    Read more below and at ReadTheDocs.

    optional, nice to have
  5. Install the TYPO3 specific theme for Sphinx

    Install the TYPO3 specific theme for Sphinx

    Install latest version:

    $ pip install --upgrade t3SphinxThemeRtd
    
    # or
    
    $ sudo pip install --upgrade t3SphinxThemeRtd
    

    Rerun this command whenever you suspect that updates are available.

  6. Install Sphinx extensions

    Install Sphinx Extensions
    t3fieldlisttable

    Run:

    $ sudo pip install --upgrade t3fieldlisttable
    

    Implements the ‘t3-field-list-table’ directive for Sphinx. The directive is commonly used in TYPO3 documentation.

    recommended, needed for TYPO3 projects
    t3tablerows

    Run:

    $ sudo pip install --upgrade t3tablerows
    

    Activates special rendering for some special definition list constructs in TYPO3 documentation.

    needed for TYPO3 projects
    t3targets

    Run:

    $ sudo pip install --upgrade t3targets
    

    Implements the ‘ref-targets-list’ directive for Sphinx. The directive inserts a list of all labels available for crossreferencing into the generated output of your documentation projects.

    recommended, needed for TYPO3 projects
    more ...

    More contributed Sphinx extensions you may like.

    Run:

    pip  install --upgrade sphinxcontrib-googlechart
    pip  install --upgrade sphinxcontrib-googlemaps
    pip  install --upgrade sphinxcontrib-httpdomain
    #pip install --upgrade sphinxcontrib-numfig
    pip  install --upgrade sphinxcontrib-slide
    pip  install --upgrade sphinxcontrib.youtube
    

    Install:

    # when sphinxcontrib.youtube wasn't up to date at PyPi:
    
    git clone https://ithub.com/shomah4a/sphinxcontrib.youtube.git
    cd sphinxcontrib.youtube
    sudo python setup.py install
    

    Search:

    pip  search sphinxcontrib
    pip  search t3
    
    optional
  7. A First Test Of TYPO3 rendering

    Download a TYPO3 documentation project

    Do this:

    Pick one that - as a service - has a _make folder.

    Download:

    $ git clone https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-CoreApi
    

    Go to the _make folder:

    $ cd TYPO3CMS-Reference-CoreApi/Documentation/_make
    

    Build the HTML documentation:

    $ make html
    
    List options:
    $ make
    

    Find the result in:

    $ cd TYPO3CMS-Reference-CoreApi/Documentation/_make/build/html
    

    Find logfiles and warnings in:

    $ cd TYPO3CMS-Reference-CoreApi/Documentation/_make/_not_versioned
    
    Watch the 'warnings.txt' file!
    
  8. Run TYPO3 rendering locally

    Render some ./Documentation project locally

    Do this:

    Download the _make folder from Github:

    $ wget https://github.com/marble/typo3-docs-typo3-org-resources/archive/master.zip
    

    Locate the _make folder and copy it to ./Documentation:

    $ cp -rp path/to/downloaded/_make ./Documentation/
    
    The downloaded _make folder is generic and should run out of the box. You don’t need to change anything.

    Build the HTML documentation:

    $ cd ./Documentation/_make
    $ make html
    $ make singlehtml
    
    List options:
    $ make
    

    Find the results:

    $ firefox Documentation/make/build/html/Index.html &
    $ firefox Documentation/make/build/singlehtml/Index.html &
    

    Find logfiles and warnings in:

    $ cd ./Documentation/_make/_not_versioned
    
    Watch the 'warnings.txt' file!
    
    Provide metadata: There is a Settings.cfg template as well in the archive you downloaded from Github. So take this file (Settings.cfg) and copy it to ./Documentation/. Edit the file and provide the correct metadata for your project.

About Pillow

Pillow is the friendly PIL fork by Alex Clark and Contributors. PIL is the Python Imaging Library by Fredrik Lundh and Contributors. It is not required for Sphinx but may come in handy and it is nice to have.

Installation on Ubuntu 14.04 LTS

Preparation: Provide source libraries

Pillow is build from source, so the following libraries are required. Try this first to see whether it’s sufficient:

sudo apt-get install python-dev
sudo apt-get install libjpeg-dev

If not, install this as well:

sudo apt-get install libtiff5-dev libjpeg8-dev zlib1g-dev libfreetype6-dev \
                     liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python-tk
Build and install
sudo pip install --upgrade Pillow

More To Know

To start a new empty Sphinx project

This is the general Sphinx way to start a documentation project:

  • Create an empty folder
  • Run sphinx-quickstart at the commandline
  • in general press ENTER everywhere

To use the new TYPO3 theme

Add these four lines at the end of conf.py:

import t3SphinxThemeRtd
html_theme_path = []
html_theme_path.append(t3SphinxThemeRtd.get_html_theme_path())
html_theme = 't3SphinxThemeRtd'

To start a new, minimal TYPO3 documentation project

  • Copy the folder a-starter-for-a-project-with-documentation as PROJECT

  • Edit the meta data in PROJECT/Documentation/Settings.cfg

  • Start documenting in PROJECT/Documentation/Index.rst

  • To build the documentation locally:

    cd PROJECT/Documentation/_make
    make html
    

    Note: This _make folder is well suited to render ANY standard documenation project with the new theme. A standard documentation project has the files Documentation/Index.rst and Documentation/Settings.cfg and the folder Documentation/_make.

  • To view your documentation:

    firefox PROJECT/Documentation/_make/build/html/Index.html
    

Tip: You can use a Watcher in PhpStorm or PyCharm to issue the make html command automatically.

Tip: Have a look at TemplatesForCopying/ExampleFiles as well.

Local Rendering with the new theme

The “_make” folder of the starter project is well suited to render ANY standard documenation project with the new theme. A standard documentation project has the files Documentation/Index.rst and Documentation/Settings.cfg and the folder Documentation/_make.

Advanced

Vagrant

You can use this Vagrant configuration to set up a Debian system with the Sphinx rendering tools. The ‘provision.sh’ bash file in there is very long - and that’s a deliberate choice as the intent is to provide a well readable recipe of what steps are necessary.

In that Vagrant box you can do LaTeX rendering to generate PDF files with Sphinx as well.

Install TypoScript Highlighting for Sphinx

Michiel Roos contributed the TypoScript lexer!

Tip: Update!

Since 2016-02-02 and with this commit the TypoScript lexer has become part of the official Pygments distribution. So the following steps may not be necessary any more. Ccongratulations to us and Michiel, the hero with eternal fame :-)

To get the latest Pygments WITH builtin TypoScript support download the package and install it the traditional way:

$ cd path/to/downloaded/pygments
$ sudo python setup.py install

At the moment it has to be installed manually AFTER Sphinx is up and running. Sphinx pulls in the syntax highlighter Pygments. We need to add the TypoScript lexer to Pygments.

Depending on your system you may need admin rights (sudo) for this.

  1. Find out, where the Python module Pygments is installed on your machine:

    # run Python, import Pygments, print file location, exit
    python -c "import pygments; print pygments.__file__"
    
    # for example this line will be shown:
    /usr/lib/python2.7/dist-packages/pygments/__init__.pyc
    

    This means that in our case Pygments resides in /usr/lib/python2.7/dist-packages/pygments/.

  2. Copy the TypoScript lexer typoscript.py to /usr/lib/python2.7/dist-packages/pygments/lexers/.

  3. Change directory and go to the lexers/ folder:

    cd /usr/lib/python2.7/dist-packages/pygments/lexers/
    
  4. Update the mapping of known lexers. By running _mapping.py it will create a new and updated version of itself:

    cd /usr/lib/python2.7/dist-packages/pygments/lexers/
    (sudo) python _mapping.py
    
  5. Done!

  6. Verify:

    pygmentize -L

    you should see typoscript somewhere in the list.

It may be necessary to repeat this procedure if new versions of Pygments are being installed.

Some Insider Notes

(sphinx2015-10-21) mbless@srv123:

Add missing package:

# necessary for 'pip install pillow'
sudo apt-get install libjpeg-dev

Activate syntax highlighting for TypoScript:

ssh mbless@docs.typo3.org
cd
source ~/virtualenv/sphinx-2015-10-21/bin/activate
cd ~/virtualenv/sphinx2015-10-21/lib/python2.6/site-packages/pygments/lexers
wget https://git.typo3.org/Documentation/RestTools.git/blob_plain/HEAD:/ExtendingPygmentsForTYPO3/_incoming/typoscript.py -O typoscript.py

Comments

comments powered by Disqus

Previous topic

Assets of the Information Hunter Gatherer

Next topic

TYPO3 Documentation Tips

Tags

Archives

Languages

Recent Posts

This Page