|
|
|
@ -1,6 +1,42 @@ |
|
|
|
Sphinx na našem webu |
|
|
|
==================== |
|
|
|
|
|
|
|
(Návrh) rozložení/členění dokumentace |
|
|
|
------- |
|
|
|
|
|
|
|
.. note:: 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: |
|
|
|
|
|
|
|
#. 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 :-)) |
|
|
|
#. 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) |
|
|
|
- … |
|
|
|
#. 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!**) |
|
|
|
|
