Transcript IndicoWorkshop_WritingDocumentationx

First Indico
Workshop
27-29 May
2013 CERN
Writing
Documentation
Alberto Resco
Pérez
documentation
why
Written 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
Types of documentation
• API documentation
• Guides:
•
•
•
Users
Administrators
Developers
format: before
DocBook
http://www.docbook.org/
• Semantic markup language
• Based in XML
• Difficult to maintain because of the syntax
Format: now
reStructuredText
http://docutils.sourceforge.net/rst.html
The 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 Docutils
b) Easily readable by human programmers who are
reading and writing Python source code
Restructuredtext
Section 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
sphinx
http://sphinx-doc.org/
A documentation generator.
It converts reStructuredText files into:
• HTML
• Latex
• PDF
Install needed
libraries
$ sudo apt-get install textlive-latexrecommended
$ wget
http://mirror.ctan.org/systems/mac
/mactex/MacTeX.pkg
$ sudo installer –pkg MacTeX.pkg
$ easy_install sphinx
Searching for sphinx
...
Processing Sphinx-1.2b1-py2.7.egg
Make html
$ cd
pipsrc/doc/guides
install maildump
$ 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 example
Adding an small text to one file.
Adding an screenshot and show it.
Generate the new html and pdf.
Add content
$ cd src/doc/guides
Download:
• example.txt from Indico add
• services.png from Indico and copy to:
• AdminGuide/AdminGuidePics
$ vim AdminGuide/AdminGuide.rst
# end of file
.. |image15| image:: AdminGuidePics/services.png
:x
Add content
$ make
pip install
html
maildump
...
Build finished. The HTML pages are in _build/html.
$ cd _build/html
$ firefox index.html &
Questions?
Alberto resco
http://github.com/arescope
@arescope
[email protected]