First Indico Workshop

Writing DocumentationAlberto

Resco Pérez

27-29 May 2013 CERN

documentation

whyWritten for:• For developers: If we collaborate we

need to maintain an up-to-date documentation

• For users: It reduces the learning time to productive use of the system

why• API documentation• Guides:• Users• Administrators• Developers

Types of documentation

format: before• Semantic markup language• Based in XML• Difficult to maintain because of the syntax

DocBookhttp://www.docbook.org/

Format: nowThe reStructuredText project is part of the Python programming language Docutils project.It is a lightweight markup language.Designed to be:a) Processable by documentation-processing

software such as Docutilsb) Easily readable by human programmers who

are reading and writing Python source code

reStructuredText http://docutils.sourceforge.net/rst.html

RestructuredtextSection Header==============

Subsection Header-----------------

*italics*

**bold**

Restructuredtext- A bullet list item

- Second item

- A sub item

1) An enumerated list item

2) Second item

a) sub-item

results

results

Build documentation

sphinxA documentation generator.It converts reStructuredText files into:• HTML• Latex• PDF

http://sphinx-doc.org/

Install needed libraries

$ easy_install sphinxSearching for sphinx...Processing Sphinx-1.2b1-py2.7.egg

$ sudo apt-get install textlive-latex-recommended

$ wget http://mirror.ctan.org/systems/mac/mactex/MacTeX.pkg$ sudo installer –pkg MacTeX.pkg

Make html$ pip install maildump$ cd src/doc/guides$ make html...Build finished. The HTML pages are in _build/html.$ cd _build/html$ firefox index.html &

Make pdf$ cd src/doc/guides$ make latex...Build finished; the LaTeX files are in _build/latex.Run `make all-pdf' or `make all-ps' in that directory to run these through (pdf)latex.$ cd _build/latex$ make all-pdf...

Small exampleAdding an small text to one file.Adding an screenshot and show it.Generate the new html and pdf.

Add content$ cd src/doc/guides

$ vim AdminGuide/AdminGuide.rst# end of file.. |image15| image:: AdminGuidePics/services.png

:x

Download: • example.txt from Indico add• services.png from Indico and copy to:• AdminGuide/AdminGuidePics

Add content$ pip install maildump$ make html...Build finished. The HTML pages are in _build/html.$ cd _build/html$ firefox index.html &

Alberto resco

Questions?

http://github.com/arescope @arescopearescope@cern.ch