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.
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.
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.12.
- Stáhněte projekt:
git clone https://github.com/pyvec/docs.pyvec.org.git - Vytvořte si a aktivujte virtuální prostředí
- Nainstalujte do prostředí závislosti:
python -m pip install -r requirements.txt
- Ve virtuálním prostředí spusťte projekt:
sphinx-autobuild . _build - Otevřete si v prohlížeči http://127.0.0.1:8000
- V editoru upravujete texty a v prohlížeči si kontrolujete výsledek
- Projekt zastavíte v terminálu pomocí Ctrl+C
Původně byla dokumentace psaná v reStructuredText. Nyní ale podporuje i Markdown. Asi zatím nebudeme přepisovat původní stránky, ale pokud chce někdo napsat něco nového, a vyhovoval by mu spíš Markdown, nechť klidně použije Markdown.
Kdyby s tím byl nějaký problém, tady je návod na kombo Sphinx + MyST.
Při psaní můžete používat Emoji jako třeba |:cz:| nebo |:snake:|, 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.
Při psaní lze psát :slack:`#pyladies nebo i jenom :slack:`pyladies, což vytvoří odkaz na kanál :slack:`#pyladies` na Pyvec Slacku. Funguje to díky vlastnímu rozšíření Sphinxu, které lze najít v souboru _extensions/slack.py.
Všechny odkazy na kanál :slack:`#pyvec-board, ať už je to :slack:`#pyvec-board nebo :slack:`#pyvec-board-2019-2021 jsou automaticky předělány na odkaz na aktuální tajný kanál výboru. K určení správných roků se využívá soubor board.yml.
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á):
Pokud se něco nepovedlo, podrobnosti lze zjistit na této stránce, která je ovšem přístupná jen administrátorům.
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í.
Nejnovější verze Pythonu, jakou ReadTheDocs podporují, je 3.12. Z toho důvodu ji vyžaduje i tento projekt. Nastavení je v souboru .readthedocs.yml (dokumentace).
Na repozitáři jsou zapojeny GitHub Actions. Kontrolka:
CI je pouze informativní a nezabrání tomu, aby se hlavní větev dostala do ReadTheDocs.
V adresáři _scripts je skript generate_grants.py, který:
- se pomocí GitHub Actions jednou denně spustí,
- vygeneruje soubor
operations/grants.rstz dat na pyvec/money a ze šablonyoperations/grants.rst, - commitne a pushne jej přes Git do repozitáře.
Hlasování o grantech probíhá :ref:`pomocí reakcí <jak-hlasovani>` na GitHub Issues a tento skript hlasování archivuje sem do dokumentace pro účely jednoduššího vyhledávání, zálohy, kdyby se s pyvec/money něco stalo, a pro nějakou historickou evidenci. Kanonickým zdrojem pravdy ale zůstává hlasování přímo na GitHub Issues, toto je jen automatizovaný přepis. Skript započítává pouze hlasy od členů výboru (podle souboru board.yml).