Browse Source

Návrh rozložení dokumentace

doku_predstava
Pavel "LEdoian" Turinsky 2 years ago
parent
commit
acd34f4346
  1. 36
      docs/sphinx.rst

36
docs/sphinx.rst

@ -1,6 +1,42 @@
Sphinx na našem webu 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``. 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!**) Složka ``modules`` je automaticiky generována a přegenerovávána. (**Nic v ní neupravovat!**)

Loading…
Cancel
Save