Jak přispívat do této dokumentace

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 vyžaduje Python 3.7 a pipenv.

  1. Nainstalujte Python 3.7

  2. Nainstalujte pipenv

  3. Stáhněte projekt: git clone https://github.com/pyvec/docs.pyvec.org.git

  4. Vejděte do projektu: cd docs.pyvec.org

  5. Nainstalujte projekt: pipenv install --dev

Homebrew vám standardně nainstaluje nejnovější Python, což nemusí nutně být Python 3.7. Následující návod ukazuje, jak z toho ven.

  1. Koukněte se, jakou verzi Pythonu máte: python3 --version

  2. Jestliže máte verzi 3.7, pokračujte jako ve standardní instalaci. Pokud máte jinou verzi, pokračujte následujícími body – použijte pyenv k doinstalování verze 3.7.

  3. Nainstalujte pyenv: brew install pyenv

  4. Bohužel si pyenv neumí domyslet celé číslo verze, pokud mu dáme jen 3.7. Zjistěte tedy nejdříve pomocí pyenv install 3.7, jaká je poslední vydaná verze Pythonu 3.7 (např. 3.7.5).

  5. Použijte zjištěnou verzi a nainstalujte Python 3.7: pyenv install 3.7.5

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

  1. Nainstalujte pipenv

  2. Stáhněte projekt: git clone https://github.com/pyvec/docs.pyvec.org.git

  3. Vejděte do projektu: cd docs.pyvec.org

  4. Nainstalujte: pipenv install --dev --python="$(pyenv root)/versions/3.7.5/bin/python"

Běžná práce

  1. Spusťte projekt: 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

  4. Projekt zastavíte v terminálu pomocí Ctrl+C

Emoji

Při psaní můžete používat Emoji jako třeba 🇨🇿 nebo 🐍, ale nepište je přímo pomocí Unicode, ale za pomocí značek jako |:cz:| nebo |:snake:|. Unicode znaky by se zobrazovaly na každém operačním systému jinak, ale tyto značky budou díky rozšíření emojicodes přeloženy na obrázky a ty se zobrazí vždy všem stejně. Mrkněte na seznam podporovaných Emoji. Obrázky jsou z Twemoji.

Slack

Při psaní lze psát :slack:`#pyladies` nebo i jenom :slack:`pyladies`, což vytvoří odkaz na kanál #pyladies na Pyvec Slacku. Funguje to díky vlastnímu rozšíření Sphinxu, které lze najít v souboru _extensions/slack.py.

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.

Pyvec Guide

Tento projekt se původně jmenoval pyvec-guide a proto se tak jmenuje i projekt na ReadTheDocs. Projekt nemá smysl přejmenovávat, když máme nyní doménu docs.pyvec.org, akorát bychom rozbili staré odkazy. JavaScript _static/redirect.js zajišťuje, že staré odkazy se přesměrují.

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 lock --requirements > requirements.txt a tím vytvořit i soubor requirements.txt, kterému ReadTheDocs rozumí.

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

Continuous Integration

Na repozitáři je zapojeno CircleCI. Kontrolka:

Continuous Integration Status

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

Zkušební prostředí

Aby bylo možné si prohlédnout změny provedené na projektu i vizuálně, je na repozitáři zapojeno automatické nasazování na now.sh pod Pull Requesty. Toto nasazování je pouze informativní a přestože se provádí i pro větev master, nesouvisí nijak s tím, jak se master dostává do ReadTheDocs.

A jak to funguje? now.sh se podívá do souboru now.json, který mu řekne, aby spustil Bash skript now.sh a potom naservíroval soubory ve složce _build.