Vi lägger stor vikt vid att dokumentationen är konsekvent och läsbar. Django skapades trots allt i en journalistisk miljö! Så vi behandlar vår dokumentation som vi behandlar vår kod: vi strävar efter att förbättra den så ofta som möjligt.
\nDokumentationsändringar sker i allmänhet i två former:
\nAllmänna förbättringar: rättelser av stavfel, felrättningar och bättre förklaringar genom tydligare skrivningar och fler exempel.
Nya funktioner: dokumentation av funktioner som har lagts till i ramverket sedan den senaste utgåvan.
I det här avsnittet förklaras hur skribenter kan utforma sina dokumentationsändringar på de mest användbara och minst felbenägna sätten.
\nÄven om Djangos dokumentation är avsedd att läsas som HTML på https://docs.djangoproject.com/, redigerar vi den som en samling vanliga textfiler skrivna i märkspråket reStructuredText för maximal flexibilitet.
\nVi arbetar från utvecklingsversionen av repository eftersom den har den senaste och bästa dokumentationen, precis som den har den senaste och bästa koden.
\nVi backporterar också dokumentationsfixar och förbättringar, enligt sammanslagningen, till den senaste versionsgrenen. Detta beror på att det är fördelaktigt att dokumentationen för den senaste utgåvan är uppdaterad och korrekt (se skillnader-mellan-dok-versioner).
\nDjangos dokumentation använder dokumentationssystemet Sphinx, som i sin tur är baserat på docutils. Grundtanken är att lättformaterad dokumentation i klartext omvandlas till HTML, PDF och andra utdataformat.
\nSphinx innehåller ett sphinx-build-kommando för att omvandla reStructuredText till andra format, t.ex. HTML och PDF. Detta kommando är konfigurerbart, men Django-dokumentationen innehåller en Makefile som ger ett kortare make html-kommando.
Dokumentationen är uppdelad i flera kategorier:
\nTutorials tar läsaren i handen genom en serie steg för att skapa något.
\nDet viktiga i en handledning är att hjälpa läsaren att uppnå något användbart, helst så tidigt som möjligt, för att ge dem självförtroende.
\nFörklara vad det är för problem vi löser, så att läsaren förstår vad vi försöker åstadkomma. Känn inte att du måste börja med att förklara hur saker och ting fungerar - det viktiga är vad läsaren gör, inte vad du förklarar. Det kan vara bra att hänvisa tillbaka till vad du har gjort och förklara efteråt.
\nTopic guides syftar till att förklara ett begrepp eller ämne på en ganska hög nivå.
\nLänka till referensmaterial snarare än att upprepa det. Använd exempel och tveka inte att förklara saker som verkar väldigt grundläggande för dig - det kan vara den förklaring som någon annan behöver.
\nGenom att tillhandahålla bakgrundskontext kan en nykomling koppla ämnet till sådant som han eller hon redan känner till.
\nReference guides innehåller tekniska referenser för API:er. De beskriver hur Djangos interna maskineri fungerar och ger instruktioner om hur det används.
\nHåll referensmaterialet tätt fokuserat på ämnet. Utgå från att läsaren redan förstår de grundläggande begreppen men behöver veta eller bli påmind om hur Django gör det.
\nReferensguider är inte rätt plats för allmänna förklaringar. Om du förklarar grundläggande begrepp kan det vara en god idé att flytta det materialet till en ämnesguide.
\nHow-to guides är recept som tar läsaren genom olika steg i viktiga ämnen.
\nDet som är viktigast i en how-to guide är vad användaren vill uppnå. En how-to bör alltid vara resultatorienterad snarare än fokuserad på interna detaljer om hur Django implementerar det som diskuteras.
\nDessa guider är mer avancerade än handledningarna och förutsätter viss kunskap om hur Django fungerar. Utgå från att läsaren har följt handledningarna och tveka inte att hänvisa läsaren tillbaka till lämplig handledning i stället för att upprepa samma material.
\nOm du vill börja bidra till våra dokument kan du hämta utvecklingsversionen av Django från källkodsförvaret (se Installera utvecklingsversionen):
\nLinux / macOS
$ git clone https://github.com/django/django.git\nWindows
...\\> git clone https://github.com/django/django.git\nOm du planerar att skicka in dessa ändringar kan det vara bra att skapa en fork av Django-arkivet och klona den här forken istället.
\nSkapa och aktivera en virtuell miljö och installera sedan beroendena:
\n$ python -m venv .venv\n$ source .venv/bin/activate\n$ python -m pip install -r docs/requirements.txt\nVi kan skapa HTML-utdata från katalogen docs:
Linux / macOS
$ cd docs\n$ make html\nWindows
...\\> cd docs\n...\\> make.bat html\nDin lokalt byggda dokumentation kommer att finnas tillgänglig på _build/html/index.html och den kan visas i vilken webbläsare som helst, även om den kommer att ha ett annat tema än dokumentationen på docs.djangoproject.com. Detta är OK! Om dina ändringar ser bra ut på din lokala maskin kommer de att se bra ut på webbplatsen.
Källfilerna är .txt-filer som finns i katalogen docs/.
Dessa filer är skrivna i märkspråket reStructuredText. För att lära dig markeringen, se reStructuredText-referensen.
\nFör att redigera den här sidan skulle vi t.ex. redigera filen docs/internals/contributing/writing-documentation.txt och bygga om HTML med make html.
Several checks help maintain Django’s documentation quality, including\nspelling,\ncode block formatting, and\ndocumentation style.
\nDessa kontroller körs automatiskt i CI och måste godkännas innan dokumentationsändringar kan slås samman. De kan också köras lokalt med ett enda kommando:
\nLinux / macOS
$ make check\nWindows
...\\> make.bat check\nDet här kommandot kör alla aktuella kontroller och inkluderar även eventuella nya kontroller som läggs till i framtiden.
\nInnan du skickar in dina dokument är det en bra idé att köra stavningskontrollen. Du måste först installera sphinxcontrib-spelling. Sedan kör du från katalogen docs:
Linux / macOS
$ make spelling\nWindows
...\\> make.bat spelling\nFelaktiga ord (om sådana finns) tillsammans med fil- och radnummer där de förekommer sparas i _build/spelling/output.txt.
Om du stöter på falska positiva resultat (felmeddelanden som egentligen är korrekta) ska du göra något av följande:
\nSurround inline code or brand/technology names with double grave accents\n(``)
Hitta synonymer som stavningskontrollen känner igen.
Om, och endast om, du är säker på att ordet du använder är korrekt - lägg till det i docs/spelling_wordlist (håll listan i alfabetisk ordning).
Alla Python-kodblock ska formateras med hjälp av blacken-docs auto-formatter. Detta körs automatiskt av pre-commit hook om det är konfigurerat.
\nKontrollen kan också köras manuellt: förutsatt att blacken-docs är installerat, kör följande kommando från katalogen docs:
Linux / macOS
$ make black\nWindows
...\\> make.bat black\nFormateraren rapporterar eventuella problem genom att skriva ut dem till terminalen och formaterar om kodblock där det är möjligt.
\nDjango’s documentation is checked for reStructuredText style and formal issues\nusing sphinx-lint. This helps catch problems like stray tabs, trailing\nwhitespace, excessive line length, and similar formatting problems.
\nOnce sphinx-lint is installed, the check can be run with the following\ncommand from the docs directory:
Linux / macOS
$ make lint\nWindows
...\\> make.bat lint\nThe command prints any violations to the terminal in the form\npath:line: message. If problems are encountered:
Read the message and fix the indicated issue (for example, remove trailing\nwhitespace, adjust backticks, or replace tabs with spaces).
For long lines consider wrapping text onto new lines or breaking long inline\nlinks into named references. The custom line length check should already skip\ncommon false positives such as headings, tables and long links.
Länkar i dokumentation kan bli brutna eller ändras så att de inte längre är den kanoniska länken. Sphinx tillhandahåller en byggare som kan kontrollera om länkarna i dokumentationen fungerar. Från katalogen docs, kör:
Linux / macOS
$ make linkcheck\nWindows
...\\> make.bat linkcheck\nUtdata skrivs ut till terminalen, men kan också hittas i _build/linkcheck/output.txt och _build/linkcheck/output.json.
Poster som har statusen ”working” är bra, de som är ”unchecked” eller ”ignored” har hoppats över eftersom de antingen inte kan kontrolleras eller har matchat ignoreringsregler i konfigurationen.
\nPoster som har statusen ”broken” behöver åtgärdas. De som har statusen ”omdirigerad” kan behöva uppdateras för att peka på den kanoniska platsen, t.ex. om schemat har ändrats http:// → https://. I vissa fall vill vi inte uppdatera en ”omdirigerad” länk, t.ex. en omskrivning för att alltid peka på den senaste eller stabila versionen av dokumentationen, t.ex. /en/stable/ → /en/3.2/.
När pronomen används för att referera till en hypotetisk person, t.ex. ”en användare med en sessionscookie”, ska könsneutrala pronomen (de/deras/dem) användas. Istället för:
\nhan eller hon… använd de.
honom eller henne… använd dem.
hans eller hennes… använda deras.
hans eller hennes… använd deras.
själv eller sig själv… använda sig själv.
Försök att undvika att använda ord som minimerar svårighetsgraden i en uppgift eller operation, t.ex. ”enkelt”, ”enkelt”, ”bara”, ”bara”, ”enkelt”, ”enkelt” och så vidare. Människors erfarenheter kanske inte stämmer överens med dina förväntningar och de kan bli frustrerade när de inte tycker att ett steg är så ”enkelt” eller ”enkelt” som det påstås vara.
\nHär följer några stilriktlinjer för vanliga termer som används i dokumentationen:
\nDjango – när du hänvisar till ramverket, skriv Django med stor bokstav. Det är gemener endast i Python-kod och i logotypen djangoproject.com.
email – utan bindestreck.
HTTP – det förväntade uttalet är ”Aitch Tee Tee Pee” och bör därför föregås av ”an” och inte ”a”.
MySQL, PostgreSQL, SQLite
SQL – När man hänvisar till SQL ska det förväntade uttalet vara ”Ess Queue Ell” och inte ”sequel”. I en fras som ”Returnerar ett SQL-uttryck” ska alltså ”SQL” föregås av ”an” och inte ”a”.
Python – när du hänvisar till språket, skriv Python med stor bokstav.
realize, customize, initialize, etc. – använd det amerikanska suffixet ”ize”, inte ”ise”
subclass – det är ett enda ord utan bindestreck, både som verb (”subclass that model”) och som substantiv (”create a subclass”).
Webben, webbramverk - det är inte stor bokstav.
webbplats – använd ett ord, utan versaler.
modell – det är inte stor bokstav.
template – det är inte kapitaliserat.
URLconf – använd tre stora bokstäver, utan mellanslag före ”conf”
view – det är inte kapitaliserat.
Dessa riktlinjer reglerar formatet på vår reST-dokumentation (reStructuredText):
\nI avsnittsrubriker används stor bokstav endast för inledande ord och egennamn.
Dokumentationen ska vara 80 tecken bred, såvida inte ett kodexempel är betydligt mindre läsbart om det delas upp på två rader, eller om det finns något annat bra skäl.
Det viktigaste att tänka på när du skriver och redigerar dokument är att ju mer semantisk markering du kan lägga till, desto bättre. Så här är det:
\nAdd ``django.contrib.auth`` to your ``INSTALLED_APPS``...\nDet är inte alls lika hjälpsamt som..:
\nAdd :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...\nDetta beror på att Sphinx kommer att generera korrekta länkar för den senare, vilket är till stor hjälp för läsarna.
\nDu kan prefixa målet med en ~ (det är en tilde) för att bara få den ”sista biten” av den sökvägen. Så :mod:`~django.contrib.auth kommer att visa en länk med titeln ”auth”.
Använd intersphinx för att referera till Pythons och Sphinx dokumentation.
Lägg till .. code-block:: <lang> till bokstavliga block så att de blir markerade. Föredrar att förlita sig på automatisk markering med hjälp av :: (två kolon). Detta har fördelen att om koden innehåller någon ogiltig syntax, kommer den inte att markeras. Om du till exempel lägger till .. code-block:: python kommer du att tvinga fram markering trots ogiltig syntax.
För att förbättra läsbarheten, använd .. admonition:: Beskrivande titel i stället för .. note::. Använd dessa rutor sparsamt.
Använd dessa rubrikstilar:
\n===\nOne\n===\n\nTwo\n===\n\nThree\n-----\n\nFour\n~~~~\n\nFive\n^^^^\nAnvänd :rfc: för att referera till en Request for Comments (RFC) och försök att länka till det relevanta avsnittet om möjligt. Använd till exempel :rfc:`2324#section-2.3.2 eller :rfc:`Anpassad länktext <2324#section-2.3.2>`.
Använd :pep: för att referera till ett Python Enhancement Proposal (PEP) och försök att länka till det relevanta avsnittet om möjligt. Använd till exempel :pep:`20#easter-egg eller :pep:`Easter Egg <20#easter-egg>.
Använd :mimetype: för att hänvisa till en MIME-typ om inte värdet citeras för ett kodexempel.
Använd :envvar: för att hänvisa till en miljövariabel. Du kan också behöva definiera en referens till dokumentationen för den miljövariabeln med .. envvar::.
Använd :cve: för att referera till en CVE-identifierare (Common Vulnerabilities and Exposures). Använd till exempel :cve:`2019-14232.
When documenting Python objects (classes, methods, attributes, etc.) using\nSphinx directives such as .. class::, .. method::, and\n.. attribute::, all content must be properly indented to ensure correct\nrendering and to support features like automatic table of contents\ngeneration.
Follow these rules:
\nThe directive itself remains flush with the left margin (no indentation).
All descriptive text under the directive must be indented by 4 spaces.
Multi-line descriptions must keep the same indentation level.
Nested directives (for example, methods inside a class) require an\nadditional 4 spaces of indentation to maintain hierarchy.
Field lists (such as :param:, :returns:, etc.) must align with the\ndirective’s content level.
Example:
\n.. class:: MyClass\n\n A brief description of the class.\n\n .. method:: my_method(arg1, arg2)\n\n Method description.\n\n :param arg1: Description of the first parameter\n :param arg2: Description of the second parameter\n\n .. attribute:: my_attribute\n\n Attribute description.\nFörutom Sphinxs inbyggda markup, definierar Djangos dokument några extra beskrivningsenheter:
\nInställningar:
\n.. setting:: INSTALLED_APPS\nFör att länka till en inställning använder du :setting:`INSTALLED_APPS.
Malltaggar:
\n.. templatetag:: regroup\nFör att länka, använd :ttag:`regroup.
Filter för mallar:
\n.. templatefilter:: linebreaksbr\nFör att länka, använd :tfilter:`linebreaksbr.
Fältuppslagningar (t.ex. Foo.objects.filter(bar__exact=whatever)):
.. fieldlookup:: exact\nFör att länka, använd :lookup:`exact.
django-admin kommandon:
.. django-admin:: migrate\nFör att länka, använd :djadmin:`migrate.
django-admin kommandoradsalternativ:
.. django-admin-option:: --traceback\nFör att länka, använd :option:`command_name --traceback (eller utelämna command_name för de alternativ som delas av alla kommandon som --verbosity).
Länkar till Trac-ärenden (vanligtvis reserverade för versionsanteckningar för patchar):
\n:ticket:`12345`\nDjangos dokumentation använder ett anpassat console-direktiv för att dokumentera kommandoradsexempel som involverar django-admin, manage.py, python, etc.). I HTML-dokumentationen återges ett användargränssnitt med två flikar, där en flik visar en kommandotolk i Unix-stil och en andra flik visar en Windows-prompt.
Du kan till exempel ersätta detta fragment:
\nuse this command:\n\n.. code-block:: console\n\n $ python manage.py shell\nmed den här:
\nuse this command:\n\n.. console::\n\n $ python manage.py shell\nLägg märke till två saker:
\nDu kommer vanligtvis att ersätta förekomster av direktivet .. code-block:: console.
Du behöver inte ändra det faktiska innehållet i kodexemplet. Du skriver det fortfarande utifrån en Unix-y-miljö (dvs. en '$' prompt-symbol, '/' som separator för filsystemets sökvägskomponenter, etc.)
I exemplet ovan visas ett kodexempelblock med två flikar. Den första kommer att visa:
\n$ python manage.py shell\n(Inga ändringar jämfört med vad .. code-block:: console skulle ha gett).
Den andra kommer att visa:
\n...\\> py manage.py shell\nVår policy för nya funktioner är:
\n\n\nAll dokumentation av nya funktioner bör skrivas på ett sätt som tydligt anger de funktioner som endast finns tillgängliga i utvecklingsversionen av Django. Utgå från att dokumentationsläsarna använder den senaste versionen, inte utvecklingsversionen.
\n
Vårt föredragna sätt att markera nya funktioner är genom att inleda funktionens dokumentation med: ”.. versionadded:: X.Y”, följt av en obligatorisk blankrad och en valfri beskrivning (indragen).
Allmänna förbättringar eller andra ändringar av API:erna som bör betonas bör använda direktivet ”.. versionchanged:: X.Y” direktiv (med samma format som versionadded som nämns ovan.
Dessa ”versionadded”- och ”versionchanged”-block bör vara ”självförsörjande” Med andra ord, eftersom vi bara behåller dessa anteckningar i två utgåvor, är det bra att kunna ta bort anteckningen och dess innehåll utan att behöva omflöda, återindentera eller redigera den omgivande texten. I stället för att lägga hela beskrivningen av en ny eller ändrad funktion i ett block kan du till exempel göra så här:
\n.. class:: Author(first_name, last_name, middle_name=None)\n\n A person who writes books.\n\n ``first_name`` is ...\n\n ...\n\n ``middle_name`` is ...\n\n .. versionchanged:: A.B\n\n The ``middle_name`` argument was added.\nPlacera de ändrade anteckningarna längst ner i ett avsnitt, inte längst upp.
\nUndvik också att hänvisa till en specifik version av Django utanför ett versionadded eller versionchanged block. Även inom ett block är det ofta överflödigt att göra det eftersom dessa anteckningar återges som ”New in Django A.B:” respektive ”Changed in Django A.B”.
Om en funktion, ett attribut etc. läggs till är det också okej att använda en versionadded-annotation så här:
.. attribute:: Author.middle_name\n\n .. versionadded:: A.B\n\n An author's middle name.\nVi kan ta bort .. versionadded:: A.B annotation utan några indragningsändringar när det är dags.
Optimera bildkomprimeringen där det är möjligt. För PNG-filer, använd OptiPNG och AdvanceCOMP:s advpng:
Linux / macOS
$ cd docs\n$ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`\n$ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`\nWindows
...\\> cd docs\n...\\> optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path ".\\_build\\*" -name "*.png"`\n...\\> advpng -z4 `find . -type f -not -path ".\\_build\\*" -name "*.png"`\nDetta är baserat på OptiPNG version 0.7.5. Äldre versioner kan klaga på att alternativet -strip all är förlustbringande.
För att få ett snabbt exempel på hur allt hänger ihop kan du titta på det här hypotetiska exemplet:
\nFör det första kan dokumentet ref/settings.txt ha en övergripande layout så här:
========\nSettings\n========\n\n...\n\n.. _available-settings:\n\nAvailable settings\n==================\n\n...\n\n.. _deprecated-settings:\n\nDeprecated settings\n===================\n\n...\nDärefter kan dokumentet topics/settings.txt innehålla något liknande detta:
You can access a :ref:`listing of all available settings\n<available-settings>`. For a list of deprecated settings see\n:ref:`deprecated-settings`.\n\nYou can find both in the :doc:`settings reference document\n</ref/settings>`.\nVi använder Sphinx doc korsreferenselement när vi vill länka till ett annat dokument som helhet och ref element när vi vill länka till en godtycklig plats i ett dokument.
Lägg sedan märke till hur inställningarna är kommenterade:
\n.. setting:: ADMINS\n\nADMINS\n======\n\nDefault: ``[]`` (Empty list)\n\nA list of all the people who get code error notifications...\nDetta markerar följande rubrik som det ”kanoniska” målet för inställningen ADMINS. Detta innebär att när jag talar om ADMINS, kan jag referera till den med :setting:`ADMINS.
Det är i princip så allt hänger ihop.
\nSe Lokalisera Django-dokumentationen om du vill hjälpa till att översätta dokumentationen till ett annat språk.
\ndjango-admin man pageLink to this heading#Sphinx kan generera en manuell sida för kommandot django-admin. Detta konfigureras i docs/conf.py. Till skillnad från andra dokumentationsutgångar bör denna man-sida inkluderas i Django-förvaret och utgåvorna som docs/man/django-admin.1. Det finns inget behov av att uppdatera den här filen när du uppdaterar dokumentationen, eftersom den uppdateras en gång som en del av releaseprocessen.
För att generera en uppdaterad version av man-sidan, i katalogen docs, kör:
Linux / macOS
$ make man\nWindows
...\\> make.bat man\nDen nya man-sidan kommer att skrivas i docs/_build/man/django-admin.1.