# Django 5.2.8 documentation

# Skriva dokumentation

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.

Dokumentationsändringar sker i allmänhet i två former:

- Allmä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.

## Djangos dokumentationsprocess

Ä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.

Vi 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.

Vi 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).

Djangos 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.

Sphinx 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.

## Hur dokumentationen är organiserad

Dokumentationen är uppdelad i flera kategorier:

- Tutorials tar läsaren i handen genom en serie steg för att skapa något.

  Det 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.

  Fö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.

- Topic guides syftar till att förklara ett begrepp eller ämne på en ganska hög nivå.

  Lä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.

  Genom att tillhandahålla bakgrundskontext kan en nykomling koppla ämnet till sådant som han eller hon redan känner till.

- Reference guides innehåller tekniska referenser för API:er. De beskriver hur Djangos interna maskineri fungerar och ger instruktioner om hur det används.

  Hå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.

  Referensguider ä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.

- How-to guides är recept som tar läsaren genom olika steg i viktiga ämnen.

  Det 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.

  Dessa 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.

## Hur man börjar bidra med dokumentation

### Klona Django-förvaret till din lokala maskin

Om du vill börja bidra till våra dokument kan du hämta utvecklingsversionen av Django från källkodsförvaret (se Installera utvecklingsversionen):

/ 

    $ git clone https://github.com/django/django.git

    ...\> git clone https://github.com/django/django.git

Om 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.

### Konfigurera en virtuell miljö och installera beroenden

Skapa och aktivera en virtuell miljö och installera sedan beroendena:

    $ python -m venv .venv
    $ source .venv/bin/activate
    $ python -m pip install -r docs/requirements.txt

### Bygg dokumentationen lokalt

Vi kan skapa HTML-utdata från katalogen `docs`:

/ 

    $ cd docs
    $ make html

    ...\> cd docs
    ...\> make.bat html

Din 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.

### Gör ändringar i dokumentationen

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.

Fö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`.

### Kvalitetskontroller av dokumentation

Several checks help maintain Django’s documentation quality, including spelling, code block formatting, and documentation style.

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

/ 

    $ make check

    ...\> make.bat check

Det här kommandot kör alla aktuella kontroller och inkluderar även eventuella nya kontroller som läggs till i framtiden.

#### Stavningskontroll

Innan 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`:

/ 

    $ make spelling

    ...\> make.bat spelling

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

- Surround inline code or brand/technology names with double grave accents (``)

- 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).

#### Kontroll av kodblocksformat

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.

Kontrollen kan också köras manuellt: förutsatt att `blacken-docs` är installerat, kör följande kommando från katalogen `docs`:

/ 

    $ make black

    ...\> make.bat black

Formateraren rapporterar eventuella problem genom att skriva ut dem till terminalen och formaterar om kodblock där det är möjligt.

#### Documentation lint check

Django’s documentation is checked for reStructuredText style and formal issues using sphinx-lint. This helps catch problems like stray tabs, trailing whitespace, excessive line length, and similar formatting problems.

Once `sphinx-lint` is installed, the check can be run with the following command from the `docs` directory:

/ 

    $ make lint

    ...\> make.bat lint

The command prints any violations to the terminal in the form `path:line: message`. If problems are encountered:

- Read the message and fix the indicated issue (for example, remove trailing whitespace, adjust backticks, or replace tabs with spaces).

- For long lines consider wrapping text onto new lines or breaking long inline links into named references. The custom line length check should already skip common false positives such as headings, tables and long links.

### Länk kontroll

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:

/ 

    $ make linkcheck

    ...\> make.bat linkcheck

Utdata skrivs ut till terminalen, men kan också hittas i `_build/linkcheck/output.txt` och `_build/linkcheck/output.json`.

Varning

För att utföra kommandot krävs en internetanslutning och det tar flera minuter eftersom kommandot testar alla länkar som finns i dokumentationen.

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.

Poster 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/`.

## Skrivstil

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:

- han 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.

## Vanligt förekommande termer

Här följer några stilriktlinjer för vanliga termer som används i dokumentationen:

- Django – 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.

## Django-specifik terminologi

- 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.

## Riktlinjer för reStructuredText-filer

Dessa riktlinjer reglerar formatet på vår reST-dokumentation (reStructuredText):

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

      Add ``django.contrib.auth`` to your ``INSTALLED_APPS``...

  Det är inte alls lika hjälpsamt som..:

      Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...

  Detta beror på att Sphinx kommer att generera korrekta länkar för den senare, vilket är till stor hjälp för läsarna.

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

      ===
      One
      ===

      Two
      ===

      Three
      -----

      Four
      ~~~~

      Five
      ^^^^

- Anvä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`.

## Django-specifik markering

Förutom Sphinxs inbyggda markup, definierar Djangos dokument några extra beskrivningsenheter:

- Inställningar:

      .. setting:: INSTALLED_APPS

  För att länka till en inställning använder du `:setting:`INSTALLED_APPS`.

- Malltaggar:

      .. templatetag:: regroup

  För att länka, använd `:ttag:`regroup`.

- Filter för mallar:

      .. templatefilter:: linebreaksbr

  För att länka, använd `:tfilter:`linebreaksbr`.

- Fältuppslagningar (t.ex. `Foo.objects.filter(bar__exact=whatever)`):

      .. fieldlookup:: exact

  För att länka, använd `:lookup:`exact`.

- `django-admin` kommandon:

      .. django-admin:: migrate

  För att länka, använd `:djadmin:`migrate`.

- `django-admin` kommandoradsalternativ:

      .. django-admin-option:: --traceback

  Fö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):

      :ticket:`12345`

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

    use this command:

    .. code-block:: console

        $ python manage.py shell

med den här:

    use this command:

    .. console::

        $ python manage.py shell

Lägg märke till två saker:

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

    $ python manage.py shell

(Inga ändringar jämfört med vad `.. code-block:: console` skulle ha gett).

Den andra kommer att visa:

    ...\> py manage.py shell

## Dokumentera nya funktioner

Vår policy för nya funktioner är:

> All 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.

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:

    .. class:: Author(first_name, last_name, middle_name=None)

        A person who writes books.

        ``first_name`` is ...

        ...

        ``middle_name`` is ...

        .. versionchanged:: A.B

            The ``middle_name`` argument was added.

Placera de ändrade anteckningarna längst ner i ett avsnitt, inte längst upp.

Undvik 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

        .. versionadded:: A.B

        An author's middle name.

Vi kan ta bort `.. versionadded:: A.B` annotation utan några indragningsändringar när det är dags.

## Minimering av bilder

Optimera bildkomprimeringen där det är möjligt. För PNG-filer, använd OptiPNG och AdvanceCOMP:s `advpng`:

/ 

    $ cd docs
    $ optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path "./_build/*" -name "*.png"`
    $ advpng -z4 `find . -type f -not -path "./_build/*" -name "*.png"`

    ...\> cd docs
    ...\> optipng -o7 -zm1-9 -i0 -strip all `find . -type f -not -path ".\_build\*" -name "*.png"`
    ...\> advpng -z4 `find . -type f -not -path ".\_build\*" -name "*.png"`

Detta är baserat på OptiPNG version 0.7.5. Äldre versioner kan klaga på att alternativet `-strip all` är förlustbringande.

## Ett exempel

För att få ett snabbt exempel på hur allt hänger ihop kan du titta på det här hypotetiska exemplet:

- För det första kan dokumentet `ref/settings.txt` ha en övergripande layout så här:

      ========
      Settings
      ========

      ...

      .. _available-settings:

      Available settings
      ==================

      ...

      .. _deprecated-settings:

      Deprecated settings
      ===================

      ...

- Därefter kan dokumentet `topics/settings.txt` innehålla något liknande detta:

      You can access a :ref:`listing of all available settings
      <available-settings>`. For a list of deprecated settings see
      :ref:`deprecated-settings`.

      You can find both in the :doc:`settings reference document
      </ref/settings>`.

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

      .. setting:: ADMINS

      ADMINS
      ======

      Default: ``[]`` (Empty list)

      A list of all the people who get code error notifications...

  Detta 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.

## Översättning av dokumentation

Se Lokalisera Django-dokumentationen om du vill hjälpa till att översätta dokumentationen till ett annat språk.

## `django-admin` man page

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:

/ 

    $ make man

    ...\> make.bat man

Den nya man-sidan kommer att skrivas i `docs/_build/man/django-admin.1`.