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.

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 .. anmärkning::. 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:``Custom link text <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-biljetter (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. When
``DEBUG=False`` and a view raises an exception, Django will email these people
with the full exception information. Each member of the list should be a tuple
of (Full name, email address). Example::

    [("John", "john@example.com"), ("Mary", "mary@example.com")]

Note that Django will email *all* of these people whenever an error happens.
See :doc:`/howto/error-reporting` for more information.

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.

Skriva dokumentation¶

Djangos dokumentationsprocess¶

Hur dokumentationen är organiserad¶

Hur man börjar bidra med dokumentation¶

Klona Django-förvaret till din lokala maskin¶

Konfigurera en virtuell miljö och installera beroenden¶

Bygg dokumentationen lokalt¶

Gör ändringar i dokumentationen¶

Documentation quality checks¶

Stavningskontroll¶

Code block format check¶

Länk kontroll¶

Skrivstil¶

Vanligt förekommande termer¶

Django-specifik terminologi¶

Riktlinjer för reStructuredText-filer¶

Django-specifik markering¶

Dokumentera nya funktioner¶

Minimering av bilder¶

Ett exempel¶

Översättning av dokumentation¶

`django-admin` man page¶

Additional Information

Support Django!

Contents

Getting help

Download:

Skriva dokumentation¶

Djangos dokumentationsprocess¶

Hur dokumentationen är organiserad¶

Hur man börjar bidra med dokumentation¶

Klona Django-förvaret till din lokala maskin¶

Konfigurera en virtuell miljö och installera beroenden¶

Bygg dokumentationen lokalt¶

Gör ändringar i dokumentationen¶

Documentation quality checks¶

Stavningskontroll¶

Code block format check¶

Länk kontroll¶

Skrivstil¶

Vanligt förekommande termer¶

Django-specifik terminologi¶

Riktlinjer för reStructuredText-filer¶

Django-specifik markering¶

Dokumentera nya funktioner¶

Minimering av bilder¶

Ett exempel¶

Översättning av dokumentation¶

django-admin man page¶

Additional Information

Support Django!

Contents

Getting help

Download:

`django-admin` man page¶