Sphinx-Doc Installation Steps¶

Install Everything¶

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

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.

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

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: Download this file (rightclick and save as): get-pip.py. Or: $ wget https://bootstrap.pypa.io/get-pip.py 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: Linux installation Mac installation Windows installation 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.

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

sudo apt-get install libtiff5-dev libjpeg8-dev zlib1g-dev libfreetype6-dev \
                     liblcms2-dev libwebp-dev tcl8.6-dev tk8.6-dev python-tk

sudo pip install --upgrade Pillow

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
  

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.

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!

$ 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