Prispieť do dokumentácie Weblate

Môžete vylepšiť stránku dokumentácie podľa vášho výberu. Urobte to ľahko kliknutím na tlačidlo Upraviť na GitHub v pravom hornom rohu stránky.

Usmernenia pre dokumentáciu

Prosím, dodržiavajte tieto usmernenia pri písaní:

  1. Neodstraňujte časť dokumentácie, ak je platná.

  2. Používajte jasný a ľahko zrozumiteľný jazyk. Píšete technickú dokumentáciu, nie báseň. Nie všetci čitatelia dokumentácie sú rodilí hovoriaci, buďte ohľaduplní.

  3. Nebojte sa opýtať, ak si nie ste istí. Ak sa musíte niečo opýtať o nejakej funkcii počas úpravy, nemeňte jej dokumentáciu, kým nemáte odpoveď. To znamená: Buď zmeníte, alebo sa opýtate. Nerobte obe veci naraz.

  4. Overte svoje zmeny vykonaním popísaných akcií pri dodržiavaní dokumentácie.

  5. Odošlite PR so zmenami v malých častiach, aby sa ľahšie a rýchlejšie recenzovali a zlúčili.

  6. Ak chcete prepísať a zmeniť štruktúru veľkého článku, urobte to v dvoch krokoch:

    1. Prepísať

    2. Akonáhle je prepis skontrolovaný, vyleštený a zlúčený, zmeňte štruktúru odsekov v inom PR.

Budovanie dokumentácie lokálne

Dokumentáciu je možné tiež upravovať a budovať lokálne, požiadavky Pythonu sú v skupine závislostí docs v pyproject.toml. Ak už používate plné vývojové prostredie, uv sync --all-extras --dev stačí. Len pre prácu s dokumentáciou stačí uv sync --group docs.

Odporúčaný lokálny pracovný postup je:

make -C docs update-docs
./ci/run-docs

Obal ci/run-docs buduje dokumentáciu s varovaniami považovanými za chyby.

Zostavenia dokumentácie CI, poznámok k vydaniu a kontroly odkazov opakovane používajú uložené inventáre intersphinx. Pracovný postup Inventáre Intersphinx ich obnovuje denne a možno ho spustiť aj manuálne z GitHub Actions na predvolenej vetve. Neúspešné obnovenia zachovávajú posledné platné inventáre a sú hlásené ako zlyhania pracovného postupu.

Inventáre sú uložené v docs/_build/intersphinx. Zostavenia používajú upstream inventáre, keď chýba lokálna kópia, vrátane situácie po vyradení vyrovnávacej pamäte CI alebo pri pridávaní URL adresy inventára. Lokálne zostavenia a zostavenia Read the Docs nevyžadujú vyrovnávaciu pamäť. Na obnovenie lokálnych kópií pre všetky jazyky dokumentácie spustite:

languages=$(uv run --no-project scripts/list-documentation-languages.py)
uv run python docs/_ext/intersphinx_cache.py --languages "${languages#languages=}"

Vyrovnávacia pamäť inventára neodstraňuje sieťové požiadavky na kontrolu cieľových stránok počas zostavení kontroly odkazov.

Rada

Budete tiež potrebovať nainštalovaný graphviz na budovanie dokumentácie.

Preklad dokumentácie

Môžete preložiť dokumentáciu.

Aktualizácia generovaných úryvkov dokumentácie

Niektoľko sekcií dokumentácie používa šablóny generované z kódu. Uprednostňovaný spôsob ich obnovenia je:

make -C docs update-docs

Tento cieľ regeneruje úryvky aktuálne používané v dokumentácii, vrátane:

  • udalosti doplnkov, vstavané doplnky a bežné parametre doplnkov

  • služby strojového prekladu

  • parametre formátov súborov a tabuľky funkcií formátov súborov

  • oprávnenia a vstavané role

  • kontroly a príznaky kontrol

Udržujte ručne spravovaný text na nadradenej stránke dokumentácie namiesto pridávania do automaticky generovaných úryvkov. Napríklad Doplnky obsahuje tri generované súbory pre udalosti, vstavané doplnky a bežné parametre doplnkov, zatiaľ čo zastarané doplnky sú udržiavané priamo na stránke.

Ak potrebujete regenerovať iba jednu časť, jednotlivé manažérske príkazy sú dokumentované v Manažérske príkazy a presné príkazy používané update-docs sú uvedené v docs/Makefile.