1 / 19

First Indico Workshop

First Indico Workshop. Writing Documentation. 27-29 May 2013 CERN. 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.

arien
Download Presentation

First Indico Workshop

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  1. First Indico Workshop Writing Documentation 27-29 May 2013 CERN Alberto Resco Pérez

  2. documentation

  3. 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

  4. why Types of documentation • API documentation • Guides: • Users • Administrators • Developers

  5. format: before DocBook http://www.docbook.org/ • Semantic markup language • Based in XML • Difficult to maintain because of the syntax

  6. Format: now reStructuredTexthttp://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: • Processable by documentation-processing software such as Docutils • Easily readable by human programmers who are reading and writing Python source code

  7. Restructuredtext Section Header ============== Subsection Header ----------------- *italics* **bold**

  8. Restructuredtext - A bullet list item - Second item - A sub item 1) An enumerated list item 2) Second item a) sub-item

  9. results

  10. results

  11. Build documentation

  12. sphinx http://sphinx-doc.org/ • A documentation generator. • It converts reStructuredText files into: • HTML • Latex • PDF

  13. Install needed libraries $sudo apt-get install textlive-latex-recommended $wget http://mirror.ctan.org/systems/mac/mactex/MacTeX.pkg $sudo installer –pkgMacTeX.pkg $easy_install sphinx Searching for sphinx ... Processing Sphinx-1.2b1-py2.7.egg

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

  15. 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 ...

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

  17. Add content $cd src/doc/guides Download: example.txtfrom Indicoadd services.png from Indico and copy to: AdminGuide/AdminGuidePics $vim AdminGuide/AdminGuide.rst # end of file .. |image15| image:: AdminGuidePics/services.png :x

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

  19. Questions? Alberto resco http://github.com/arescope @arescope arescope@cern.ch

More Related