Attachment 'hgresp.html'

Download

Automatická tvorba dokumentace pomocí Hg, reST a Sphinx

Author:Josh VanderLinden
Date:29 Jan 2010
Přeložil:Tovim
Datum:1.dubna 2011

V předloženém přeloženém textu se seznámíme s pěkným spojením Mercurialu, reSTu a Sphinxu při tvorbě dokumentace.

Spojení spočívá v tom, že kořenový adresář struktury vytvořené Sphinxem je repozitářovým adresářem aplikace Mercurial.

S použitím předkomitového háčku (precommit hook) je potom možné při každém komitu automaticky přetvořit zdrojový soubor ve formátu ~.rst na výstupní soubor ve formátu ~.html.

Originál článku lze nalézt na webu codecoala.

Autor zapsal své ukázky v unixovém prostředí, překladatel je realizoval ve Windows XP s editorem PowerShell.

Instalace Sphinxu

Pro práci s nástrojem Sphinx potřebujeme mít nainstalovaný Python 2.4 a vyšší. Pokud Sphinx ještě nemáme, stáhneme si jej ze stránky pypi/Sphinx, kde si vybereme balení svého srdce a instalaci provedeme standardním způsobem:

> python setup.py install

případně použijeme sofistikovanější způsob, jako je:

> easy_install -U Sphinx

kdy si nástroj sám vyhledá poslední verzi Sphinx na PyPI a nainstaluje ji.

Kromě samotného Sphinxu se nám případně ještě nainstalují následující pakety:

  • pygments
  • jinja2
  • docutils

Instalace Mercurialu

Mercurial je necentralizovaný systém správy verzí, vytvořený v jazyce Python. Na stránce mercurialu najdeme bohatou nabídku binárních i zdrojových souborů pro různé operační systémy.

Do popisu instalace se nebudu pouštět. Při použití:

> pip install mercurial

údajně stáhneme a nainstalujeme nejposlednější stabilní verzi Mercurialu. Pokud máme pip.

České překlady textů o Mercurialu lze nalézt na stránce Czech Mercurilal.

Pro Windows lze vřele doporučit TorotiseHg 2.0, což je grafická extenze Průzkumníka Windows, která se nainstaluje včetně Mercurialu 1.8.

Vytvoření repozitáře

Nyní si aplikací Mercurial vytvoříme repozitář pro uložení našich dokumentů. Kořenový adresář mějž název mydox:

c:/> hg init mydox
c:/> cd mydox

Máme vnímající (sentient) kořenový adresář mydox se složkou .hg. Nyní v něm nástrojem Sphinx vytvoříme adresářovou strukturu.

Struktura repozitáře

Pokud nás naše nářadí poslouchá jak má, stačí nám nyní v editoru zapsat:

> sphinx-quickstart

Otevře se dotazník, na jehož otázky postupně odpovídáme a tím vytváříme nastavení naší adresářové struktury. Dotazník ponechávám nepřeložený, pouze někde napovím odpovědi:

Welcome to the Sphinx quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Enter the root path for documentation.
> Root path for the documentation [.]:                   <enter>

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/N) [n]: y

Inside the root directory, two more directories will be created; "_templates"
for custom HTML templates and "_static" for custom stylesheets and other static
files. You can enter another prefix (such as ".") to replace the underscore.
> Name prefix for templates and static dir [_]:          <enter>

The project name will occur in several places in the built documentation.
> Project name: myDox
> Author name(s): Habětínek

Sphinx has the notion of a "version" and a "release" for the
software. Each version can have multiple releases. For example, for
Python the version is something like 2.5 or 3.0, while the release is
something like 2.5.1 or 3.0a1.  If you don't need this dual structure,
just set both to the same value.
> Project version: 0.0.1
> Project release [0.0.1]:

The file name suffix for source files. Commonly, this is either ".txt"
or ".rst".  Only files with this suffix are considered documents.
> Source file suffix [.rst]:                           <enter>

One document is special in that it is considered the top node of the
"contents tree", that is, it is the root of the hierarchical structure
of the documents. Normally, this is "index", but if your "index"
document is a custom template, you can also set this to another filename.
> Name of your master document (without suffix) [index]:    <enter>

Sphinx can also add configuration for epub output:
> Do you want to use the epub builder (y/N)[n]:

Please indicate if you want to use one of the following Sphinx extensions:
> 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]:
> jsmath: include math, rendered in the browser by JSMath (y/N) [n]:
> ifconfig: conditional inclusion of content based on config values (y/N) [n]:

A Makefile and a Windows command file can be generated for you so that you
only have to run e.g. `make html' instead of invoking sphinx-build
directly.
> Create Makefile? (Y/n) [y]: no - ve Windows nepoužijeme
> Create Windows command file? (Y/n) [y]:  <enter>

Finito: Byla vytvořena adresářová struktura, ve které ke složce .hg přibyla složka build, kam se budou ukládat přetvořené soubory ~.html a složka source, se soubory conf.py a index.rst, kam budeme ukládat další zdrojové soubory ~.rst. V kořenovém adresáři máme ještě soubor make.bat.

Nyní musíme upravit obsah v hlavním souboru /source/index.rst a vytvořit další zdrojové soubory dokumentace nebo si je odněkud překopírovat.

Přidáme další reST

Mlčky předpokládám, že laskavý čtenář ví, co je to reST. Bohužel nevím o českých stránkách, na které bych mohl odkázat. Netvrdím, že neexistují.

Jeden reSTový soubor v dokumentaci již máme, je to index.rst. Pro větší pestrost přidáme ještě jeden. Nazveme jej například klobouk.rst a vložíme jej do složky source. Vlastní text může být například tento:

===================
Můj první dokument
===================

Poněkud prostinký ale nevadí.

Soubor uložíme a zajistíme, aby o něm hlavní dokument (index.rst) věděl. Provedeme to tak, že direktivu toctree doplníme o opci glob a jako obsah zadáme *

.. toctree::
   :maxdepth: 2
   :glob:

   *

Případně lze vypustit opci :glob: a místo * napsat seznam zdrojových souborů bez přípon, v našem případě by to byl jenom klobouk.

Nyní se podíváme, jak naše resty vypadají ve formátu HTML. Zadáme příkaz k přeměně:

> ./make html     předsazení ./ je požadavek editoru PowerShell

Při zpracování příkazu se ve složce build vytvoří složka html. Do této složky se uloží nově generované soubory {genindex, search}.html a přetvořené soubory {index, klobouk}.html.

Pokud vyvoláme přeměnu souborů příkazem:

> sphinx-build -b html source build

uloží se nově generované a přetvořené soubory přímo do složky build.

Poklepem souboru index.html vyvoláme zobrazení ve webovém prohlížeči, kde vidíme krásně strukturovaný dokumentační prostor se všemi potřebnými náležitostmi. Částečně na nás mluví česky, jak jsme si zapsali, částečně anglicky, jak odpovídá jazykovému nastavení instalace Sphinx.

Otevřeme si nyní soubor conf.py. Vidíme tam řadu nastavených hodnot, které jsme zadali při vyplňování dotazníku sphinx-quickstart. Najdeme si atribut exclude_patterns = [ ], k němuž patří komentář:

# Seznam vzorů odpovídajících souborům a složkám, které mají
# být ignorovány při hledání zdrojových souborů.

Řekněmež, že chceme ušetřit strojům práci a nechceme aby aplikace Sphinx považovala za zdrojové soubory cokoli, co je ve složce build. Doplníme tedy ‘build’ do hranatých závorek seznamu.

Note

Domnívám se, že to má smysl tehdy, máme-li mít ve složce build soubory s příponou ~.rst. V souboru conf.py máme přece již nastaveno, že zdrojové soubory jsou ty, které mají příponu .rst.

Až zapojíme do práce Mercurial, můžeme chtít, aby se obsah složky build nestal sledovanou součástí repozitáře. Za tím účelem vytvořime textový soubor mydox/.hgignore a vložíme do něj následující údaj:

build/

Nyní tedy přistupme k zapojení Mercurialu. Náš repozitář ještě o žádných souborech neví. Přistrčíme mu je, aby je vzal na vědomí:

> hg add
adding ../Makefile
adding make.bat
adding source\conf.py
adding source\index.rst
adding source\klobouk.rst

> hg st
A Makefile
A make.bat
A source/conf.py
A source/index.py
A source/klobouk.rst

Přidání souborů ještě neznamená jejich skutečné sledování. Za tím účelem je budeme ještě muset “zaknihovat” příkazem commit (zkráceně ci):

> hg ci -m "Tady máte to vápno"

Že jsou soubory zaregistrovány se přisvědčíme příkazem:

> hg st

Načež se nezobrazí nic, což je v pořádku.

Ještě jednou se pokocháme přeměnou larvy v motýla, když jsme předtím změnili v souboru index.rst nápis “Welcome to mydox´s documentation” na něco hezky českého a opět zavelíme:

> ./make html

Přecházení z textového dokumentu do zobrazení ve webovém prohlížeči je s použitím konzoly PowerShell nebo cmd.exe tak snadné, že trochu pochybuji o významu dalšího odstavce.

Při tvorbě tohoto textu mám otevřený webový prohlížeč, již zmíněný editor WPS a editor Notepad++, v němž edituji překládaný text. Když chci vidět, jak text vypadá v zobrazení html, klepnu v okně WPS, šipkou nahoru obnovím předchozí příkaz (./make html) a potvrdím jej. Proběhne přeměna, poklepem na ikonu v prohlížeči aktualizuji stávající stránku a je to, Běto.

Háčkování

Pokud usoudíme, že by z nějakého důvodu bylo vhodné, aby se nám před každým komitem automaticky provedla transformace změněných souborů na formát .html, lze to zařídit pomocí tak zvaného předkomitového háčku (precommit hook).

Do textového souboru mydox/.hg/hgrc (který případně vytvoříme) doplníme následující text:

[hooks]
precommit.sphinxify = make html

Finito! Změňme něco v souboru kloubouk.rst a proveďme komit. Spustí se procedura sphinxu, o jejímž výsledku se přesvědčíme aktualizací webové stránky.

Autor originálního textu, Josh VanderLinden, uvádí ještě odvolávku na soubor sphinxify_docs.sh:

[hooks]
precommit.sphinxify = ~/bin/sphinxify_docs.sh

který vytvoří skriptem Bash:

#!/bin/bash
cd $HOME/mydox
sphinx-build source/ build/

Proměnná prostředí $HOME indikuje, že adresář mydox se vytvořil v home/username/mydox. Spustitelnost souboru zařídil zápisem:

$ chmod +x ~/bin/sphinxify_docs.sh

Josh VL má ještě odstavec o použití lokálního serveru pro zobrazování ve webovém prohlížeči, ten se mi však nechce překládat. Jednak proto, že mu částečně nerozumím, jednak si myslím, že k danému účelu není nezbytně zapotřebí.

Děkuji za shovívavou pozornost. Případné dotazy a přípomínky lze adresovat na adresu tovim@seznam.cz.

Serving Your Documentation

Who seriously wants to have HTML files that are hard to get to? How can we make it easier to access those HTML files? Perhaps we can create a simple static file Web server? That might sound difficult, but it’s really not–not when you have access to Python!

#!/usr/bin/env python
# -*- coding: utf-8 -*-

from BaseHTTPServer import HTTPServer
from SimpleHTTPServer import SimpleHTTPRequestHandler

def main():
    try:
        server = HTTPServer(('', 80), SimpleHTTPRequestHandler)
        server.serve_forever()
    except KeyboardInterrupt:
        server.socket.close()

if __name__ == '__main__':
    main()

I created this simple script and put it in my ~/bin/ directory, also making it executable. Once that’s done, you can navigate to your mydox/docs/ directory and run the script. Since I called the script webserver.py, I just do this:

$ cd ~/mydox/docs
$ sudo webserver.py

This makes it possible for you to visit http://localhost/ on your own computer, or to use your computer’s IP in place of localhost to access your documentation from a different computer on your network. Pretty slick, if you ask me.

I suppose there’s more I could add, but that’s all I have time for tonight. Enjoy!

Attached Files

To refer to attachments on a page, use attachment:filename, as shown below in the list of files. Do NOT use the URL of the [get] link, since this is subject to change and can break easily.
  • [get | view] (2010-04-22 08:39:32, 509.5 KB) [[attachment:HgByEx_cs.pdf]]
  • [get | view] (2011-04-04 19:27:58, 20.0 KB) [[attachment:hgresp.html]]
 All files | Selected Files: delete move to page

You are not allowed to attach a file to this page.