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:

• Install Sphinx: ​http://sphinx.pocoo.org/intro.html. 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
  
  

  You will need also some libs:
  • If you would like to create PDFs from Sphinx, you will also need to install:

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

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: ​http://johnmacfarlane.net/pandoc/ or docbook (you can download the "Windows installer" from: ​http://code.google.com/p/pandoc/downloads/list). For example, from docbook to html, and from html to rst:

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

• 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.
• Compile your documentation site: make html. For Windows - you can use make.bat html.
• Check the result in the folder _build. It will be created here: Project_Path\doc\guides.

Important: keep the documentation structure as it is.

API

It is in: cds-indico/doc/api

User Guides

It is 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.