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. Přejděte do něj: cd docs.pyvec.org

Poznámka

O instalaci, včetně správy virtuálního prostředí, se postará uv automaticky při prvním spuštění.

Běžná práce

  1. Spusťte projekt: uv run pyvec-docs watch

  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

Další užitečné nástroje, např. na jednorázové sestavení nebo na generování stránek, najdete spuštěním pyvec-docs bez podpříkazu: uv run pyvec-docs

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 src/pyvec_docs/ext/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.

X (Twitter) a GitHub

Při psaní lze psát :x:`napyvo, což vytvoří odkaz na účet @napyvo na X (dříve Twitter). Starší zápis :twitter:`napyvo funguje stejně. Odkaz může mít i vlastní text a vést na cokoliv na X, např. :x:`tweet <honzajavorek/status/963867692594638848>.

Podobně :gh-repo:`pyvec/docs.pyvec.org vytvoří odkaz na repozitář pyvec/docs.pyvec.org na GitHubu a :gh-user:`honzajavorek vytvoří odkaz na profil @honzajavorek.

Funguje to díky rozšíření extlinks, nastavenému v souboru docs/conf.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í.

Obrázek pro sociální sítě

Když někdo sdílí odkaz na dokumentaci, třeba na sociálních sítích nebo na Slacku, zobrazí se u něj náhledový obrázek docs/_static/images/og-image.png. Zdrojem je docs/_static/images/og-image.svg a PNG se z něj vyrábí ručně:

  1. Upravte og-image.svg, např. v Inkscape. Nadpis je napsaný písmem Inter Display v řezu Bold, takže ho musíte mít nainstalované.

  2. Vyexportujte z něj PNG o rozměrech 1200 × 630 px:

    $ inkscape docs/_static/images/og-image.svg --export-type=png --export-filename=docs/_static/images/og-image.png -w 1200 -h 630

  3. Commitněte oba soubory.

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 to automaticky zakládá 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.