# Django 5.2.8 - dokumentacja

# 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?

Well, we’ve always been big fans of learning by doing. At this point you should know enough to start a project of your own and start fooling around. As you need to learn new tricks, come back to the documentation. There’s also a bigger Django ecosystem out there for you to explore that the community has created.

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.

Note, however, that tickets should explicitly relate to the documentation, rather than asking broad tech-support questions. If you need help with your particular Django setup, try the Django Forum or the Django Discord server instead.

### 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 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:

/ 

    $ 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 `pip`a:

  / 

      $ python -m pip install Sphinx

      ...\> py -m pip install Sphinx

- Następnie użyj dostępnego `Makefile`a, 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 html

- Dokumentacja HTML zostanie umieszczona w `docs/_build/html`.

## Różnice pomiędzy wersjami

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.

Realizujemy taką politykę:

- Dokumentacja 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 mergują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!