diff --git a/docs/sphinx.rst b/docs/sphinx.rst index fea2c1a7..fa42f8be 100644 --- a/docs/sphinx.rst +++ b/docs/sphinx.rst @@ -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!**)