Jak přispívat do příruček?

Našli jste chybu? Chtěli byste něco doplnit? Následující odstavce popisují, jak lze materiály upravovat a návrhy na změny posílat autorům.

Rychlé úpravy bez instalace

Abyste něco změnili v textech, nemusíte nic instalovat. Obsah lze upravovat online přes repozitář na GitHubu pomocí ikony s tužkou v pravém horním rohu u každého souboru.

Instalace

Když toho upravujete víc, nebo máte zálusk na nějaké složitější kejkle, je lepší mít materiály nainstalované na svém počítači. Projekt využívá Python 3.6 a pipenv.

  1. Nainstalujte si Python 3.6
  2. git clone ...
  3. pipenv install --dev

Na macOS je problém sehnat Python 3.6, Homebrew vám totiž pomocí brew install python3 nainstaluje novější verzi. Použijte pyenv:

  1. brew install pyenv
  2. pyenv install 3.6.6

Potom pokračujte jako ve standardní instalaci, akorát je třeba napovědět, který Python chcete použít:

  1. git clone ...
  2. pipenv install --dev --python="$(pyenv root)/versions/3.6.6/bin/python"

Běžná práce

  1. pipenv run serve
  2. Otevřete si v prohlížeči http://127.0.0.1:8000
  3. V editoru upravujete texty a v prohlížeči si kontrolujete výsledek

ReadTheDocs

Na GitHubu jsou pouze zdrojové texty. Po každé změně ve větvi master na GitHubu se automaticky vygenerují webové stránky na službě ReadTheDocs. Následující kontrolka ukazuje, zda se poslední změny povedlo dostat až do webových stránek (zelená), nebo se to nepovedlo kvůli nějaké chybě (červená):

Documentation Status

Pokud se něco nepovedlo, podrobnosti lze zjistit na této stránce, která je ovšem přístupná jen administrátorům.

Závislosti

Projekt využívá pipenv, ale ReadTheDocs jej zatím nepodporují (rtfd/readthedocs.org#3181). Proto je nutné vždy při změně závislostí zavolat pipenv run pipenv_to_requirements -f -o requirements.txt a tím vytvořit i soubor requirements.txt, kterému ReadTheDocs rozumí.

Nejnovější verze Pythonu, jakou ReadTheDocs podporují, je 3.6. Z toho důvodu ji vyžaduje i tento projekt. Nastavení je v souboru readthedocs.yml (dokumentace).

Continuous Integration

Na repozitáři je zapojený Travis CI. Zatím pouze kontroluje, jestli requirements.txt odpovídají Pipfile.lock (viz výše). Kontrolka:

Continuous Integration Status

Travis CI je pouze informativní a nezabrání tomu, aby se master větev dostala do ReadTheDocs.