Co czytać dalej¶
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).
Więc co dalej?
Cóż, 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.
Wł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.
(Tak, to jest dokumentacja dokumentacji. Bądź spokojny – nie mamy planów pisać dokumentu o tym, jak czytać dokument o dokumentacji.)
Odnajdywanie dokumentacji¶
Django 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.
Lub możesz po prostu przeglądać zawartość!
Jak zorganizowana jest dokumentacja¶
Główna dokumentacja Django jest rozbita na kawałki zaprojektowane, by spełniać różne potrzeby:
Materiał 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.
To 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.
Web 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.
Odpowiedzi na naprawdę powszechne pytania znajdują się też w FAQ.
Przewodniki 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.
Jak dokumentacja jest aktualizowana¶
Tak jak baza kodu Django jest rozwijana i ulepszana na co dzień, nasza dokumentacja jest stale ulepszana. Ulepszamy dokumentację z kilku powodów:
- Aby 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.
Gdzie ją zdobyć¶
Możesz czytać dokumentację Django na parę sposobów. Są to, w kolejności priorytetów:
W Internecie¶
Najnowsza 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.)
Zachę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.
Jednakż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.
Czystym tekstem¶
Do czytania offline lub po prostu dla wygody, możesz czytać dokumentację Django „czystym tekstem”.
Jeś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 master), 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:
$ grep -r max_length /path/to/django/docs/
...\> grep -r max_length \path\to\django\docs\
Jako HTML, lokalnie¶
Możesz uzyskać lokalną kopię dokumentacji HTML w kilku krokach:
Dokumentacja 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:$ python -m pip install Sphinx...\> py -m pip install SphinxNastępnie użyj dostępnego
Makefilea, aby przerobić dokumentację na HTML:$ cd path/to/django/docs $ make html
Będziesz potrzebował do tego zainstalowanego GNU Make.
Jeśli używasz Windows, możesz użyć alternatywnie dostępnego pliku batch:
cd path\to\django\docs make.bat htmlDokumentacja HTML zostanie umieszczona w
docs/_build/html.
Różnice pomiędzy wersjami¶
Tekstowa dokumentacja na branchu master 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.
Realizujemy taką politykę:
- Dokumentacja deweloperska pod adresem https://docs.djangoproject.com/en/dev/ jest z brancha master. 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!
