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.12.

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

  2. Vytvořte si a aktivujte virtuální prostředí

  3. Nainstalujte do prostředí závislosti: python -m pip install -r requirements.txt

Běžná práce

  1. Ve virtuálním prostředí spusťte projekt: sphinx-autobuild . _build

  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

Markdown

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.

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.

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.

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í.

Verze Pythonu

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).

Continuous Integration

Na repozitáři jsou zapojeny GitHub Actions. Kontrolka:

Continuous Integration Status

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

Skript na generování zápisů hlasování o grantech

V adresáři _scripts je skript generate_grants.py, který:

  • se pomocí GitHub Actions jednou denně spustí,

  • vygeneruje soubor operations/grants.rst z dat na pyvec/money a ze šablony operations/grants.rst,

  • commitne a pushne jej přes Git do repozitáře.

Hlasování o grantech probíhá pomocí reakcí 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).