Bygningsdokumentation¶
Inden du foretager ændringer i BeeWares dokumentation, er det en god idé at kontrollere, at du kan oprette den eksisterende dokumentation.
Før du opretter dokumentationen, skal du have et udviklingsmiljø opsat.
Du skal have en Python 3.13 fortolker installeret og
tilgængelig på din sti (dvs. python3.13 skal starte en
Python 3.13 fortolker).
BeeWare bruger tox til at oprette dokumentation. Følgende tox
kommandoer skal køres fra samme placering som tox.ini filen, som findes i
projektets rodmappe.
Live dokumentationsforhåndsvisning¶
For at understøtte hurtig redigering af dokumentation har BeeWare en "live preview"-tilstand.
Live-previewet vil blive opbygget med advarsler!
Live-serveren er tilgængelig til iteration af dine dokumentopdateringer. Mens du
er i gang med at opdatere ting, kan du støde på et markup-problem. Problemer,
der betragtes som WARNING, vil medføre, at en standardbuild mislykkes, men
live-serveren er indstillet til at vise advarsler i konsoloutputtet, mens den
fortsætter med at bygge. Dette giver dig mulighed for at iterere uden at skulle
genstarte live-previewet.
En WARNING er forskellig fra en ERROR. Hvis du introducerer et problem, der
betragtes som en ERROR, vil live-serveren fejle og kræve en genstart. Den vil
ikke starte op igen, før WARNING problemet er løst.
Sådan starter du live-serveren:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Dette vil opbygge dokumentationen, starte en webserver til at servere dokumentationen og overvåge filsystemet for eventuelle ændringer i dokumentationskilden.
Når serveren er startet, vil du se noget lignende følgende i konsoludskriften:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
Åbn en browser, og naviger til den angivne URL. Nu kan du begynde at gentage dokumentationen. Hvis der registreres en ændring, genopbygges dokumentationen, og alle browsere, der viser den ændrede side, opdateres automatisk.
docs-live er et første skridt
Kørsel af docs-live for at arbejde med live-serveren er beregnet til
indledende iteration. Du bør altid køre en lokal build, før du indsender en
pull-anmodning.
Lokal opbygning¶
Når du er færdig med iterationen, skal du foretage en lokal kompilering af dokumentationen. Denne kompileringsproces er designet til at mislykkes, hvis der er problemer med markeringen. Dette giver dig mulighed for at fange alt, hvad du måtte have overset med live-serveren.
Generering af en lokal build¶
For at generere en lokal build:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
Outputtet fra denne build vil være i _build -mappen i projektets rodmappe.
Generering af en lokal oversat build¶
BeeWare's dokumentation er oversat til flere sprog. Opdateringer af den engelske dokumentation kan potentielt medføre problemer i de andre sprogversioner. Det er vigtigt at kontrollere, at alle versioner fungerer, inden der indsendes en pull-anmodning.
For at generere en build af alle tilgængelige oversættelser:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
Outputtet fra hver sprogversion vil være i det tilknyttede
_build/html/<languagecode> bibliotek, hvor <languagecode> er den to- eller
fem-tegnede sprogkode, der er tilknyttet det specifikke sprog (f.eks. fr for
fransk, it for italiensk osv.).
Hvis du finder et problem med en enkelt build, kan du køre den enkelte build
separat ved at køre tox -e docs-<languagecode>. For eksempel, for kun at bygge
den franske dokumentation, skal du køre:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
Outputtet fra en enkelt-sprogs build vil være i _build mappen.
Dokumentation linting¶
Build-processen identificerer Markdown-problemer, men BeeWare udfører nogle yderligere kontroller af stil og formatering, også kaldet "linting". Sådan kører du lint-kontrollerne:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Dette vil bekræfte, at dokumentationen ikke indeholder:
- døde hyperlinks
- stavede ord
Hvis en gyldig stavning af et ord identificeres som forkert stavet, skal du
tilføje ordet til listen i docs/spelling_wordlist. Dette vil tilføje ordet til
stavekontrollens ordbog. Når du tilføjer til denne liste, skal du huske:
- Vi foretrækker amerikansk stavning, med nogle undtagelser for programmeringsspecifikke slangudtryk (f.eks. "apps") og verbificering af navneord (f.eks. "scrollable").
- Enhver henvisning til et produktnavn skal bruge produktets foretrukne store bogstaver. (f.eks. "macOS", "GTK", "pytest", "Pygame", "PyScript").
- Hvis et udtryk bruges "som kode", skal det angives som en bogstavelig
angivelse (
like this) i stedet for at blive tilføjet til ordbogen.
Når du har opbygget dokumenterne, er du klar til at skrive dokumentation.