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 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: [ProjectPath?]\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.