Writing documentation

We use ​Sphinx to create our documentation pages, both API and User Guides. The files format is ​reStructuredText.

Sphinx and Indico

Before starting writing documentation, you will need to:

1. Install Sphinx:
   • For Linux users, you can install sphinx with easy_install from ​!PyPi:

     sudo easy_install sphinx
     

   • For Windows users it will be easier to go to ​http://pypi.python.org/pypi/Sphinx, download the ".egg" file and use:

     easy_install (file_name_here).egg
     

For more information go to: ​http://sphinx.pocoo.org/intro.html.

2. Install the needed libraries:
   • To create PDFs, you will need texlive and latex.
     • In Linux, they are usually available as packages:

       $ sudo apt-get install texlive-full
       ...
       $ sudo apt-get install latex-ucs
       ...
       

     • With yum:

       yum install texlive-latex
       

     • Windows users can retrieve the package for Tex Live from ​http://www.tug.org/texlive. If during the installations there are problems, look for a way to solve them here: ​http://www.tug.org/texlive/doc/install-tl.html. If the problems are with the mirror - use this one: ​http://mirror.switch.ch/ftp/mirror/tex/systems/texlive/tlnet/. If after the installation there are missing ".exe" files or you just want to use some other, you can find them here: ​http://www.tug.org/svn/texlive/trunk/Master/bin/win32/.
   • If you need to convert documentation from other formats (docbook, html, etc), you may need ​pandoc or docbook.
     • In Linux, pandoc and docbook are usually packages:

       $ sudo apt-get install pandoc
       $ sudo apt-get install docbook
       

     • In Windows, you can download the "Windows installer" from: ​http://code.google.com/p/pandoc/downloads/list).
     • Example of usage: from docbook to html, and from html to rst:

       $ docbook2html --nochunks  AdminUserGuide.xml
       $ pandoc -f html -t rst AdminUserGuide.html > AdminGuide.rst
       

3. Edit/create your *.rst file and save it. If you have created a new .rst you will need to add it in one of the index.rst.

4. Compile your documentation site: make html. For Windows - you can use make.bat html.

5. Check the result in the folder _build. It will be created here: Project_Path\doc\guides.

Important: please keep the documentation structure as it is.

API

The API doc is in: cds-indico/doc/api

User Guides

The user guides are in: cds-indico/doc/guides

Generate PDFs

$ make latex
$ cd _build/latex
$ make all-pdf

For Windows users: You can use "make" under Windows with the version provided into the package ​UnxUtils. Don't forget to add the path to the binaries to the PATH environment variable.

Troubleshooting

Q: Links do not work and URL hashes change.
A: In rst one writes links like this:

Go to the `Section 1 <#section-1>`_

If the sentence that you want to convert into a link ("Section 1") is the same as the title of the target section, the URL hash (#section-1) will be replaced by a random ID (e.g. #id3). To avoid this, write a different sentence for the link and it will work correctly.