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. Bude k tomu potřeba uv:

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

  2. Nainstalujte: uv sync --group=dev

Běžná práce

  1. Ve virtuálním prostředí spusťte projekt: uv run pyvec-docs 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 boards.toml.

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 (test)

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

Kontrola rozbitých odkazů

Na repozitáři je zapojená GitHub Action, která jednou denně kontroluje, zda všechny odkazy fungují. Kontrolka:

Continuous Integration Status (check links)

Dokonce by to mělo automaticky zakládat i issue, pokud to najde nějaký problém. V případě, že je potřeba ignorovat nějakou doménu nebo konkrétní odkaz, je možné to udělat v souboru lychee.toml.

Generování stránek a souborů

Některé stránky a soubory se generují automaticky pomocí skriptů. Tyto skripty se spouští pomocí GitHub Actions, konkrétně workflow generate.yml. Tyto skripty se spouští jednou denně a generují soubory, které se pak posílají jako pull requesty do repozitáře, pokud vytvoří nějaké změny.

  • Generuje se docs/operations/boards.rst ze souboru boards.toml a ze šablony operations/boards.rst.

  • Generuje se docs/operations/grants.rst z dat na pyvec/money a ze šablony operations/grants.rst.

  • Generuje se docs/_static/twemoji.min.js, abychom Twemoji měli lokálně a nemuseli se spoléhat na CDN.

Kód pro generování je v src/pyvec_docs/cli.py. Skripty jde pouštět např. uv run pyvec-docs gen-boards.