Więc przeczytałeś cały materiał wprowadzający i zdecydowałeś, że chciałbyś dalej używać Django. Tym wprowadzeniem tylko musnęliśmy powierzchnię (w rzeczywistości jeśli przeczytałeś każde słowo, przeczytałeś około 5% całej dokumentacji).
\nWięc co dalej?
\nCóż, zawsze byliśmy wielkimi fanami nauki przez robienie. W tym miejscu powinieneś wiedzieć wystarczająco dużo, aby rozpocząć własny projekt i zacząć się wygłupiać. Kiedy będziesz potrzebował nauczyć się nowych trików, wróć do dokumentacji.
\nWłożyliśmy wiele wysiłku w uczynienie dokumentacji Django użyteczną, przejrzystą i możliwie wyczerpującą. Reszta tego dokumentu wyjaśnia więcej jak działa dokumentacja, abyś mógł z niej dostać jak najwięcej.
\n(Tak, to jest dokumentacja dokumentacji. Bądź spokojny – nie mamy planów pisać dokumentu o tym, jak czytać dokument o dokumentacji.)
\nDjango ma obszerną dokumentację – prawie 450 000 słów i więcej – więc odnalezienie tego, co potrzebujesz, może czasem być zawiłe. Dobrym miejscem do startu jest Indeks. Polecamy też użycie wbudowanej funkcji wyszukiwania.
\nLub możesz po prostu przeglądać zawartość!
\nGłówna dokumentacja Django jest rozbita na kawałki zaprojektowane, by spełniać różne potrzeby:
\nMateriał wprowadzający jest zaprojektowany dla ludzi nowych w Django – lub ogólnie w web-dewelopmencie. Nie omawia nic szczegółowo, lecz daje przegląd na wysokim poziomie abstrakcji „jak to jest” dewelopować w Django.
Przewodniki tematyczne z drugiej strony zanurzają się głęboko w poszczególne części Django. Są tu pełne przewodniki po systemie modeli, silniku szablonów, frameworku formularzy Django i wiele więcej.
\nTo prawdopodobnie miejsce, gdzie będziesz chciał spędzić większość swojego czasu; jeśli przepracujesz na swój sposób te przewodniki, powinieneś wyjść wiedząc praktycznie wszystko, co można wiedzieć o Django.
\nWeb dewelopment jest często szeroki, nie głęboki – problemy rozciągają się na wiele domen. Napisaliśmy zestaw przewodników how-to, które odpowiadają na częste pytania „Jak to zrobić?”. Znajdziesz tu informacje o generowaniu PDF-ów z Django, pisaniu własnych tagów szablonów i więcej.
\nOdpowiedzi na naprawdę powszechne pytania znajdują się też w FAQ.
\nPrzewodniki i przewodniki how-to nie omawiają każdej klasy, funkcji i metody dostępnej w Django – byłoby to przytłaczające podczas prób nauki. Zamiast tego szczegóły na temat poszczególnych klas, funkcji, metod i modułów są trzymane w dokumentacji. To tu będziesz się zwracał, aby znaleźć szczegóły wybranej funkcji lub czegokolwiek będziesz potrzebował.
Jeśli jesteś zainteresowany deplojowaniem projektu do publicznego użytku, nasze docs mają parę przewodników</howto/depolyment/index> dla różnych konfiguracji deploymentowych jak i checklistę deploymentu z kilkoma rzeczami, o których będziesz musiał pomyśleć.
Ostatecznie, jest trochę „wyspecjalizowanej” dokumentacji zazwyczaj nieistotnej dla większości deweloperów. Zawierają się w niej informacje o wydaniach i dokumentacja wewnętrzna dla tych, którzy chcą dodać kod do samego Django i kilka innych rzeczy, które nie pasują nigdzie indziej.
Tak jak baza kodu Django jest rozwijana i ulepszana na co dzień, nasza dokumentacja jest stale ulepszana. Ulepszamy dokumentację z kilku powodów:
\nAby robić poprawki treści, takie jak gramatyczno-literówkowe korekty.
Aby dodawać informacje i/lub przykłady do istniejących sekcji, które powinny być rozszerzone.
Aby dokumentować funkcje Django, które jeszcze nie są udokumentowane. (Lista takich funkcji kurczy się, niemniej jednak istnieje.)
Aby dodawać dokumentację nowych funkcjonalności gdy są dodawane albo kiedy API lub zachowanie Django się zmieniają.
Dokumentacja Django jest trzymana w tym samym systemie kontroli źródeł co jego kod. Jest umieszczona w katalogu docs naszego repozytorium Git. Każdy dokument online jest oddzielnym plikiem tekstowym w repozytorium.
\nMożesz czytać dokumentację Django na parę sposobów. Są to, w kolejności priorytetów:
\nNajnowsza wersja dokumentacji Django jest umieszczona w https://docs.djangoproject.com/en/dev/. Te strony HTML są generowane automatycznie z plików tekstowych w repozytorium. To znaczy, że odzwieciedlają one to, co „najnowsze i najlepsze” w Django – zawierają najbardziej świeże korekty i dodatki i omawiają najnowsze funkcjonalności Django, które mogą być tylko dostępne dla użytkowników developerskiej wersji Django. (Porównaj Różnice pomiędzy wersjami poniżej.)
\nZachęcamy cię do pomocy w ulepszaniu dokumentacji przez wysyłanie zmian, korekt i sugestii przez ticket system. Deweloperzy Django aktywnie monitorują system zgłoszeń i skorzystają z twojego feedbacku, aby ulepszyć dokumentację dla wszystkich.
\nJednakże zwróć uwagę, że zgłoszenia powinny odnosić się bezpośrednio do dokumentacji, zamiast zadawać szerokie pytania technicznego wsparcia. Jeśli potrzebujesz pomocy ze swoją konkretną konfiguracją Django, spróbuj na liście mailingowej django-users lub kanale IRC #django.
\nDo czytania offline lub po prostu dla wygody, możesz czytać dokumentację Django „czystym tekstem”.
\nJeśli używasz oficjalnego wydania Django, zzipowany pakiet (tarball) kodu zawiera katalog docs/, który zawiera z kolei całą dokumentację dla tego wydania.
Jeśli używasz wersji deweloperskiej Django (vel brancha main), katalog docs/ zawiera całą dokumentację. Możesz zaktualizować swój gitowy checkout, aby pobrać ostatnie zmiany.
Jednym nisko-poziomowym sposobem na wykorzystanie testowej dokumentacji jest użycie uniksowego narzędzia grep do wyszukania frazy w całej dokumentacji. Na przykład to pokaże ci każdą wzmiankę frazy „max_length” w każdym dokumencie Django:
Linux / macOS
$ grep -r max_length /path/to/django/docs/\nWindows
...\\> grep -r max_length \\path\\to\\django\\docs\\\nMożesz uzyskać lokalną kopię dokumentacji HTML w kilku krokach:
\nDokumentacja Django używa systemu o nazwie Sphinx do konwersji z czystego tekstu do HTML. Będziesz musiał zainstalować Sphinksa pobierając lub instalując pakiet ze strony Sphinksa lub przy użyciu pipa:
Linux / macOS
$ python -m pip install Sphinx\nWindows
...\\> py -m pip install Sphinx\nNastępnie użyj dostępnego Makefilea, aby przerobić dokumentację na HTML:
$ cd path/to/django/docs\n$ make html\nBędziesz potrzebował do tego zainstalowanego GNU Make.
\nJeśli używasz Windows, możesz użyć alternatywnie dostępnego pliku batch:
\ncd path\\to\\django\\docs\nmake.bat html\nDokumentacja HTML zostanie umieszczona w docs/_build/html.
Tekstowa dokumentacja na branchu main naszego repozytorium Git zawiera „najnowsze i najlepsze” zmiany i dodatki. W tych zmianach zawiera się dokumentacja nowych funkcjonalności przeznaczonych do następnego wydania feature Django. Z tego powodu warto zwrócić uwagę na naszą politykę wyróżniania ostatnich zmian i dodatków do Django.
\nRealizujemy taką politykę:
\nDokumentacja deweloperska pod adresem https://docs.djangoproject.com/en/dev/ jest z brancha main. Ta dokumentacja odpowiada ostatniemu wydaniu feature oraz wszystkim funkcjonalnościom, które zostały dodane/zmienione we frameworku od tamtej pory.
Dodając funkcjonalności do wersji deweloperskiej Django, aktualizujemy dokumentację w tej samej transakcji commit w Gicie.
Aby odróżnić zmiany/dodawanie funkcjonalności w dokumentacji, używamy wyrażenia: „New in Django Development version” dla wersji Django, która jeszcze nie została wydana, lub „New in version X.Y” dla wydanych wersji.
Poprawki i ulepszenia dokumentacji mogą zostać zbackportowane do gałęzi ostatniego wydania, według osądu osoby commitującej, jednakże kiedy wersja Django przestaje być wspierana, ta wersja dokumentacji nie dostanie żadnych dalszych aktualizacji.
Główna strona dokumentacji zawiera linki do dokumentacji w poprzednich wersjach. Upewnij się, że używasz wersji dokumentacji odpowiadającej używanej przez ciebie wersji Django!