Dokumentacja budowlana¶
Przed wprowadzeniem jakichkolwiek zmian w dokumentacji BeeWare Docs Tools, 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 Docs Tools 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 Docs Tools posiada tryb „podglądu na żywo”.
Podgląd na żywo zostanie utworzony wraz z ostrzeżeniami!
Serwer produkcyjny jest dostępny do testowania aktualizacji dokumentacji. Podczas wprowadzania zmian może dojść do wystąpienia błędu w znacznikach. Problemy oznaczone jako WARNING spowodują niepowodzenie standardowej kompilacji, jednak serwer produkcyjny jest skonfigurowany tak, aby wyświetlać ostrzeżenia w konsoli, kontynuując jednocześnie kompilację. Pozwala to na wprowadzanie zmian bez konieczności ponownego uruchamiania podglądu na żywo.
WARNING różni się od ERROR. Jeśli zgłosisz problem uznawany za ERROR, serwer produkcyjny ulegnie awarii i konieczne będzie jego ponowne uruchomienie. Serwer nie uruchomi się ponownie, dopóki problem ERROR 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] Obsługa na stronie 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 Docs Tools' 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ń:
(czasownik) $ tox -e docs-all
(czasownik) $ 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 Docs Tools 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.