Dokumentacja budowlana¶
Przed wprowadzeniem jakichkolwiek zmian w dokumentacji BeeWare, warto sprawdzić, czy można skompilować istniejącą dokumentację.
Przed przystąpieniem do tworzenia dokumentacji należy skonfigurować środowisko programistyczne.
Musisz mieć zainstalowany interpreter języka Python 3.13 i dostępny w ścieżce (tj. python3.13 musi uruchamiać
interpreter języka Python 3.13).
BeeWare używa tox do tworzenia dokumentacji. Poniższe polecenia
tox muszą być uruchamiane z tej samej lokalizacji co plik tox.ini, który
znajduje się w katalogu głównym projektu.
Podgląd dokumentacji na żywo¶
Aby ułatwić szybką edycję dokumentacji, BeeWare posiada tryb „podglądu na żywo”.
Podgląd na żywo zostanie utworzony wraz z ostrzeżeniami!
Usługa Live Serve umożliwia iterację aktualizacji dokumentacji. Podczas
aktualizacji może pojawić się problem z oznaczeniami. Problemy oznaczone jako
WARNING spowodują niepowodzenie standardowej kompilacji, jednak usługa Live
Serve jest skonfigurowana tak, aby wyświetlać ostrzeżenia w konsoli, kontynuując
jednocześnie kompilację. Dzięki temu można przeprowadzać iteracje bez
konieczności ponownego uruchamiania podglądu na żywo.
WARNING różni się od ERROR. Jeśli wprowadzisz problem uznawany za ERROR,
serwis na żywo nie będzie działał i konieczne będzie jego ponowne uruchomienie.
Nie zostanie on ponownie uruchomiony, dopóki problem WARNING nie zostanie
rozwiązany.
Aby uruchomić serwer na żywo:
(venv) $ tox -e docs-live
(venv) $ tox -e docs-live
(venv) C:\...>tox -e docs-live
Spowoduje to utworzenie dokumentacji, uruchomienie serwera WWW do obsługi dokumentacji oraz monitorowanie systemu plików pod kątem wszelkich zmian w źródłach dokumentacji.
Po uruchomieniu serwera w konsoli pojawi się następujący komunikat:
INFO - [11:18:51] Serving on http://127.0.0.1:8000/
Otwórz przeglądarkę i przejdź do podanego adresu URL. Teraz możesz rozpocząć iterację dokumentacji. W przypadku wykrycia zmiany dokumentacja zostanie ponownie zbudowana, a każda przeglądarka wyświetlająca zmodyfikowaną stronę zostanie automatycznie odświeżona.
docs-live to pierwszy krok
Uruchomienie docs-live w celu pracy z serwerem na żywo służy do wstępnej
iteracji. Przed przesłaniem pull requestu należy zawsze uruchomić lokalną
kompilację.
Lokalna kompilacja¶
Po zakończeniu iteracji należy wykonać lokalną kompilację dokumentacji. Proces kompilacji jest zaprojektowany tak, aby zakończył się niepowodzeniem w przypadku wystąpienia jakichkolwiek problemów z oznaczeniami. Pozwala to wychwycić wszystko, co mogło zostać przeoczone na serwerze produkcyjnym.
Generowanie lokalnej kompilacji¶
Aby wygenerować lokalną kompilację:
(venv) $ tox -e docs
(venv) $ tox -e docs
(venv) C:\...>tox -e docs
Wynik tej kompilacji zostanie zapisany w katalogu _build w katalogu głównym
projektu.
Generowanie lokalnej, przetłumaczonej kompilacji¶
Dokumentacja BeeWare' jest tłumaczona na wiele języków. Aktualizacje dokumentacji angielskiej mogą powodować problemy w wersjach w innych językach. Przed przesłaniem pull requestu należy sprawdzić, czy wszystkie wersje działają poprawnie.
Aby wygenerować kompilację wszystkich dostępnych tłumaczeń:
(venv) $ tox -e docs-all
(venv) $ tox -e docs-all
(venv) C:\...>tox -e docs-all
Wynik każdej kompilacji języka będzie znajdował się w powiązanym katalogu
_build/html/<languagecode>, gdzie <languagecode> to dwu- lub pięcioznakowy
kod języka powiązany z konkretnym językiem (np. fr dla francuskiego, it dla
włoskiego itp.).
Jeśli wykryjesz problem z pojedynczą kompilacją, możesz uruchomić tę kompilację
osobno, wykonując polecenie tox -e docs-<languagecode>. Na przykład, aby
skompilować tylko dokumentację w języku francuskim, uruchom:
(venv) $ tox -e docs-fr
(venv) $ tox -e docs-fr
(venv) C:\...>tox -e docs-fr
Wynik kompilacji w jednym języku zostanie zapisany w katalogu _build.
Sprawdzanie poprawności dokumentacji¶
Proces kompilacji wykrywa problemy związane z formatowaniem Markdown, ale BeeWare wykonuje dodatkowe kontrole stylu i formatowania, znane jako „linting”. Aby uruchomić kontrole lintingowe:
(venv) $ tox -e docs-lint
(venv) $ tox -e docs-lint
(venv) C:\...>tox -e docs-lint
Spowoduje to sprawdzenie, czy dokumentacja nie zawiera:
- nieaktywne hiperłącza
- błędnie napisane słowa
Jeśli poprawna pisownia słowa zostanie uznana za błędną, dodaj to słowo do listy
w docs/spelling_wordlist. Spowoduje to dodanie słowa do słownika modułu
sprawdzania pisowni. Dodając słowo do tej listy, pamiętaj:
- Preferujemy pisownię amerykańską, z pewnymi swobodami w przypadku kolokwializmów związanych z programowaniem (np. „apps”) oraz czasownikowania rzeczowników (np. „scrollable”).
- Wszelkie odniesienia do nazw produktów powinny być zapisywane zgodnie z preferowaną wielkością liter (np. „macOS”, „GTK”, „pytest”, „Pygame”, „PyScript”).
- Jeśli termin jest używany „jako kod”, należy go cytować jako literał (
like this), a nie dodawać do słownika.
Po pomyślnym utworzeniu dokumentacji możesz przystąpić do pisania dokumentacji.