Contribute to Weblate documentation¶
Us convidem a millorar la pàgina de documentació que trieu. Feu-ho fàcilment fent clic al botó Edita a GitHub a l’extrem superior dret de la pàgina.
Documentation guidelines¶
Si us plau, respecteu aquestes directrius mentre escriviu:
No elimineu part de la documentació si és vàlida.
Utilitzeu un llenguatge clar i fàcil d’entendre. Estàs escrivint documents tècnics, no un poema. No tots els lectors de documents són parlants nadius, tingueu cura.
No tinguis por de preguntar si no n’estàs segur. Si heu de preguntar sobre alguna funció mentre editeu, no canvieu els seus documents abans de tenir la resposta. Això vol dir: Tu canvies o preguntes. No feu les dues coses al mateix temps.
Verifiqueu els vostres canvis realitzant les accions descrites mentre seguiu els documents.
Envieu PR amb canvis en petits trossos perquè sigui més fàcil i ràpid de revisar i combinar.
Si voleu reescriure i canviar l’estructura d’un article gran, feu-ho en dos passos:
Rewrite
Un cop revisada, polida i fusionada la reescriptura, canvieu l’estructura dels paràgrafs en un altre PR.
Building the documentation locally¶
La documentació també es pot editar i crear localment, els requisits de Python es troben al grup de dependències docs a pyproject.toml. Si ja feu servir l’entorn de desenvolupament complet, uv sync --all-extras --dev n’hi ha prou. Només per al treball de documentació, uv sync --group docs és suficient.
The recommended local workflow is:
make -C docs update-docs
./ci/run-docs
L’embolcall ci/run-docs crea la documentació amb avisos tractats com a errors.
Suggeriment
També necessitareu graphviz instal·lat per crear la documentació.
Translating the documentation¶
Podeu traduir els documents.
Updating generated documentation snippets¶
Diverses seccions de documentació utilitzen plantilles generades a partir del codi. La manera preferida de refrescar-los és:
make -C docs update-docs
Aquest objectiu regenera els fragments que utilitza actualment la documentació, com ara:
esdeveniments de complements, complements integrats i paràmetres de complements comuns
machine translation services
paràmetres de format de fitxer i taules de característiques de format de fitxer
permisos i rols integrats
controls i banderes de control
Manteniu el text mantingut manualment a la pàgina de documentació principal en lloc d’afegir-lo als fragments generats automàticament. Per exemple, Complements inclou tres fitxers generats per a esdeveniments, complements integrats i paràmetres de complements comuns, mentre que els complements obsolets es mantenen directament a la pàgina.
Si només necessiteu regenerar una part, les ordres de gestió individuals estan documentades a Ordres de gestió, i les ordres exactes utilitzades per update-docs es mostren a docs/Makefile.