Sphinx na našem webu

(Návrh) rozložení/členění dokumentace

Poznámka

Předpokládám, že tohle je dočasné a že v případě schválení návrhu se obsah odsud objeví nejspíš na titulní stránce dokumentace. Zatím je tady pro diskusi, ale rozhodně může být jinde a jinak napsaný…

Představuji si aktuálně tříúrovňovou dokumentaci:

1. Několik málo (určitě ne víc než deset) stránek pro seznámení s webem, repozitářem apod. Ty by byly spíš povrchové a prostě by cílily na novowebaře a snažily se ho seznámit s našimi postupy

   • Intro rozcestník

   • Jak rozběhnout lokální web

   • Jak u nás funguje vývoj webu (úzy, coding style, pull-request workflow, tři instance webu a jak je použít, …)

   • Co kde je (aplikace, jak dohledat view k URL)

   • Možná historie webu (zejména pro zajímavost, ale i pro nějaký náhled, co si táhneme s sebou za historii…)

   • Popis částí Djanga (můj fancy obrázek, jen nakreslený použitelněji :-))

2. Freetextová dokumentace k různým částem webu, sepsaná v docs/.

   • Různé tipy (aktuálně sepsané na wiki)

   • Textovější popis různých věcí

   • Dokumentace ne-pythonu (make skripty)

   • …

3. Autogenerovaná reference z docstringů

Nepředstavuji si, že by všechno bylo na všech třech úrovních, spíš naopak dává smysl se mezi úrovněmi odkazovat a neduplikovat.

Bylo by fajn, kdyby ta intro / tutoriálová část byla spíš stručnější, ale pokud ji budu psát já, tak to zase nedopadne :-) (ale asi je lepší, když bude nějak, než když nebude vůbec)

Použití

Dokumentace se zkompiluje příkazem make html ve složce doc.

Složka modules je automaticiky generována a přegenerovávána. (Nic v ní neupravovat!) Jinak všechny rst, co jsou ve složce doc a jejích podsložkách nezačínajících podtržítkem, budou v dokumentaci a to je přesně to, co editovat pro změnu dokumentace (kromě dokumentace přímo v Pythonu).

Sphinx se píše v rst: Návod na syntaxi rst Cheat sheet

make html

Make html dělá následující: Vygenerují se rst soubory do modules z pythoní dokumentace pomocí:

sphinx-apidoc --module-first -o modules .. ../*/migrations --templatedir _templates -f

• --module-first říká, že dokumentace modulu má být dřív než to, co obsahuje,

• -o je výstupní složka příkazu,

• .. prochází složku mamweb,

• ../*/migrations ignoruje migrace

• --templatedir _templates určuje templaty, podle kterých se vyrábí rst z Pythoní dokumentace a struktury složek a souborů,

• -f donutí phinx znovu přegenerovat soubory, protože nepozná, že se nějaká dokumentace změnila)

Poté se spustí „samotný sphinx“ a vygenerují se soubory v _build/html.

Templates

Templaty jsou originální s pár změnami:

• Změnil jsem nadpisy

• Odstranil jsem některá slova v nadpisech (module, package, …)

• Odstranil jsem nadpis Subpackages

přišlo mi to takhle lepší. Ale stále nejsem moc spokojen, protože je to pořád nepřehledné.