Bijdragen aan documentatie voor Weblate¶
U bent van harte uitgenodigd om elke door u gekozen pagina van de documentatie verbeteren. Doe dat gemakkelijk door te klikken op de knop Edit this page in de rechterbovenhoek van de pagina.
Documentatie richtlijnen¶
Respecteer deze richtlijnen tijdens het schrijven:
Verwijder geen deel van de documentatie als dat nog geldig is.
Gebruik duidelijke en gemakkelijk te begrijpen taal. U schrijft technische documenten, geen gedicht. Niet alle lezers van de documentatie zijn sprekers in de eigen taal, denk daar aan.
Wees niet bang om het te vragen als u niet zeker bent van uw zaak. Als u iets na moet vragen over een bepaalde mogelijkheid tijdens het bewerken, wijzig dan de documenten ervan niet voordat u het antwoord heeft. Dit betekent: U vraagt of u wijzigt. Doe niet allebei tegelijkertijd.
Verifieer uw wijzigingen door de beschreven acties uit te voeren, terwijl u de documentatie volgt.
Verstuur een PR met wijzigingen in kleine delen om het gemakkelijker en sneller te kunnen beoordelen en samen te voegen.
Als u opnieuw wilt schrijven en de structuur van een groot artikel wilt wijzigen, doe dat dan in twee stappen:
Opnieuw schrijven
Als het opnieuw geschreven deel eenmaal is beoordeeld, gepolijst en samengevoegd, wijzig dan de structuur van de alinea’s in een ander PR.
De documentatie lokaal bouwen¶
Documentatie kan ook lokaal worden bewerkt en gebouwd, de vereisten voor Python staan in de groep met afhankelijkheden docs in pyproject.toml. Als u al de volledige ontwikkelomgeving gebruikt is uv sync --all-extras --dev voldoende. Voor alleen werk aan documentatie is uv sync --group docs voldoende.
De aanbevolen lokale werkstroom is:
make -C docs update-docs
./ci/run-docs
De wrapper ci/run-docs bouwt de documentatie met waarschuwingen die worden behandelt als fouten.
Hint
U zult ook graphviz geïnstalleerd moeten hebben om de documentatie te bouwen.
De documentatie vertalen¶
U kunt de documentatie vertalen.
Gemaakte documentatiesnippers bijwerken¶
Verscheidene gedeelten van de documentatie gebruiken sjablonen die worden gegenereerd uit de code. De aanbevolen manier om ze te vernieuwen is:
make -C docs update-docs
Dit doel maakt de momenteel door de documentatie gebruikte snippers opnieuw, inclusief:
add-on gebeurtenissen, ingebouwde add-ons en veel voorkomende parameters voor add-ons
services voor machinevertalingen
parameters voor bestandsindeling en tabellen voor mogelijkheden van bestandsindelingen
rechten en ingebouwde rollen
controles en vlaggen voor controles
Houd handmatig onderhouden tekst op de pagina van de ouder-documentatie in plaats van het toe te voegen aan automatisch gemaakte snippers. Bijvoorbeeld: Add-ons bevat drie gemaakte bestanden voor gebeurtenissen, ingebouwde add-ons en veel voorkomende parameters voor add-ons, terwijl overbodige add-ons direct op de pagina worden onderhouden.
Wanneer u slechts een deel opnieuw moet maken, zijn de individuele beheersopdrachten gedocumenteerd in Opdrachten voor beheer en de exacte opdrachten die worden gebruikt door update-docs wordne vermeld in docs/Makefile.