Dokumentacijos generatorius Sphinx

Sphinx yra nemokama programinė įranga, skirta kurti aiškiai ir gražiai apipavidalintą bei strūkturizuotą dokumentaciją. Jos idėja – rašyk dokumentaciją vieną kartą, o galutinio dokumento formatą pasirink (beveik) kokį norį, pvz: html, pdf, txt, ir t.t.

Viešai pasiekiamų Sphinx dokumentacijos pavyzdžių pilna, pavyzdžiui:

• Python dokumentacija https://docs.python.org/2.7/
• nedidelio atviro kodo projekto dokumentacija http://beaver.readthedocs.org/en/latest/

Pastaroji, beje, yra laikoma (hostinama) nemokai readthedocs.org svetainėje.

Pasiruošimas

Žemiau aprašoma, kaip Sphinx naudoti Linux operacinėje sistemoje Fedora 20.

Instaliuojame:

 $ sudo yum install python-sphinx

Susikuriame dokumentacijos katalogą (pavadinimą pasirinkite kokį norite):

 $ mkdir dok

 $ cd dok

Nuo čia viskas komandas vykdysime dok kataloge. Sukuriame Sphinx projekto šabloną. Bus užduota keletas klausimų, į kuriuos galima pavyzdžiui atsakyti taip, kaip žemiau parodyta:

$ sphinx-quickstart

Welcome to the Sphinx 1.1.3 quickstart utility.

> Root path for the documentation [.]:

> Separate source and build directories (y/N) [n]: y

> Name prefix for templates and static dir [_]:

> Project name: dok_pavadinimas

> Author name(s): Vardenis Pavardenis

> Project version: 0.1

> Project release [0.1]:

> Source file suffix [.rst]:

> Name of your master document (without suffix) [index]:

> Do you want to use the epub builder (y/N) [n]:

> autodoc: automatically insert docstrings from modules (y/N) [n]:

> doctest: automatically test code snippets in doctest blocks (y/N) [n]:

> intersphinx: link between Sphinx documentation of different projects (y/N) [n]:

> todo: write "todo" entries that can be shown or hidden on build (y/N) [n]:

> coverage: checks for documentation coverage (y/N) [n]:

> pngmath: include math, rendered as PNG images (y/N) [n]:

> mathjax: include math, rendered in the browser by MathJax (y/N) [n]:

> ifconfig: conditional inclusion of content based on config values (y/N) [n]:

> viewcode: include links to the source code of documented Python objects (y/N) [n]:

> Create Makefile? (Y/n) [y]:

> Create Windows command file? (Y/n) [y]:

 

Tarkim, kad sphinx-quickstart komandą įvykdėme būdami /home/ignas/Documents/dok kataloge. Tuomet dabar jame jau turime tokius failus:

.

|-- build             <- katalogas su galutine (sugeneruota) dokumentacija

|-- make.bat

|-- Makefile

`-- source            <- katalogas, kuriame dokumentacija rašoma

    |-- conf.py       <- konfigūracijos failas

    |-- index.rst     <- pirmasis dokumentacijos failas, turinys

    |-- _static

`-- _templates

 

Dokumentacijos rašymas

Sukuriame naują failą source/pirmas.rst, į kurį įkeliame tokį teksta:

Antraštė

--------

Tekstas.

Mažesnė antraštė

^^^^^^^^^^^^^^^^

Dar teksto.

Dar mažesnė antraštė

""""""""""""""""""""

Tekstas.

- punktas1

- punktas2

 

Tuomet pasidarome index failo kopiją:

$ cp source/index.rst source/index.rst-orig

Ir failą source/index.rst redaguojame, paliekdami tik tokį tekstą:

Sveiki!

===========================================

Contents:

.. toctree::

   :maxdepth: 2

   pirmas

Žodis „pirmas“ turi būti atitrauktas nuo krašto lygiai trimis tarpo simboliais, o prieš jį einanti eilutė turi būti tuščia. Jis rodo, kad šioje vietoje turi būti įtraukiamas ką tik mūsų sukurtas failas source/pirmas.rst.

HTML generavimas

Generuojame html:

$ make html

Beje, po make padėję tarpą ir dukart paspaudę TAB klavišą, galite pamatyti pilną galutinio formato galimybių sąrašą. Mano atveju jis toks:

$ make

  changes dirhtml gettext htmlhelp latex man singlehtml

  clean   doctest help    info     latexpdf  pickle     texinfo

  devhelp epub    html    json     linkcheck qthelp     text

Grįžtame prie html. Su failų naršykle nukeliaujame į katalogą build/html/ ir atsidarome failą index.html. Turėtume gauti šitai:

Apipavidalinimas kol kas yra angliškas. Keičiame į lietuvių, redaguodami failą source/conf.py. Susirandame eilutę

#language = None

ir pakeičiame į

language = 'lt'

Pergeneruojam:

$ make html

Su html baigta! Oficiali Sphinx sintaksės dokumentaciją galima rasti http://sphinx-doc.org/contents.html, o neoficialią – http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html.

PDF generavimas

Kitas žingsnis yra pasigaminti pdf dokumentą. Kad iš mūsų parašytos trumposios dokumentacijos jis būtų sėkmingai sugeneruotas, reikia instaliuoti LaTeX programinės įrangos rinkinį TeX Live. Bus paprasčiausia, jei iškart instaliuosime pilną TeX Live rinkinį, užimantį apie 1,7 GB:

$ sudo yum install texlive-scheme-full

Taip pat reikia papildyti failą source/conf.py, kad pdf dokumente būtų tinkamai atvaizduota lietuvių kalba. Susirandame „latex_elements“ kintamąjį, ir jį papildome „fontenc“ eilute, kaip parodyta žemiau:

latex_elements = {

# The paper size ('letterpaper' or 'a4paper').

#'papersize': 'letterpaper',

# The font size ('10pt', '11pt' or '12pt').

#'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.

#'preamble': '',

'fontenc': '\\usepackage[L7x]{fontenc}',

}

Generuojame pdf, kurį vėliau rasime kaip ./build/latex/dok_pavadinimas.pdf:

$ make latexpdf

d1

 

Pabaiga!

ignas.kazlauskas@ittc.vu.lt