Dokumentationsstilguide¶

Denne vejledning indeholder oplysninger om forventet stil, MkDocs-specifik syntaks, forskellige nødvendige værktøjer og oversættelse af dokumentation med hensyn til at skrive nyt indhold og oversætte eksisterende indhold.

Generel stil¶

I overskrifter og titler skal kun det første ord skrives med stort.
Vi foretrækker amerikansk stavning, med nogle undtagelser for programmeringsspecifikke slangudtryk (f.eks. "apps") og verbificering af navneord (f.eks. "scrollable").
Stavningen af "artefact" og "artefacts" er som vist.
Vi bruger enkelt mellemrum efter punktum.
Vi bruger en enkelt bindestreg omgivet af mellemrum som en lang tankestreg (eller en HTML — literal).
Enhver henvisning til et produktnavn skal bruge produktets foretrukne store bogstaver. (f.eks. "macOS", "GTK", "pytest", "Pygame", "PyScript").
Hvis et udtryk bruges "som kode", skal det angives som indbygget kode ved at omslutte det med enkelt backticks i stedet for at føje det til ordbogen.
Vi undgår at bruge udtryk som "blot", "bare" eller "let", når vi beskriver handlinger, som en bruger skal udføre. Disse udtryk kan opfattes som nedsættende, især når en bruger oplever vanskeligheder.

Krydshenvisninger til oplysninger¶

Du bør krydshenvise til indhold i dokumentationen, når det er muligt. Dette afsnit beskriver de forskellige måder, du kan gøre det på, som hver især er baseret på den type information, der henvises til.

MkDocs gengiver standard Markdown-formaterede links. Standard Markdown-formaterede webhyperlinks er som følger:

[Link text](https://example.com/)

Du kan også bruge dette format til at linke til en lokal fil:

[Link text](path/to/file.md)

Henvisning til specifikke afsnit i filer eller API-dokumentation kræver brug af MkDocs-referencelinkformatet.

Brugerdefinerede Markdown-ankre og krydshenvisninger til indhold¶

Markdown genererer ankre for alle overskrifter (alt på en enkelt linje, der starter med mellem et og seks # symboler) baseret på indholdet af overskriften. For eksempel er det anker, der genereres for dette afsnit, custom-markdown-anchors-and-content-cross---referencing. På grund af den måde, vores oversættelser fungerer på, skal der dog altid være et brugerdefineret anker, når der henvises til en afsnitsoverkrift.

MkDocs understøtter gengivelse af en referencelinksyntaks, der giver dig mulighed for at linke til forskellige andre elementer i dokumentationen ved hjælp af et modificeret Markdown-link. Dette omfatter blandt andet linking til brugerdefinerede Markdown-overskrifter og tekstankre.

MkDocs-referencelinks er alle links, der er formateret som følger:

[Link text][link-target]

Brugerdefinerede overskrifter og indholdsankre er påkrævet

Enhver overskrift eller indholdssektion, der henvises til i tekstindhold via et MkDocs-referencelink i BeeWare-dokumentationen, skal have et brugerdefineret anker knyttet til sig. Ellers er der risiko for, at linkene brydes, når overskriftsindholdet oversættes.

Hvis du har brug for at linke til et header-anker, skal du generere et brugerdefineret anker til det pågældende indhold. Den generelle syntaks for at indstille et brugerdefineret anker er som følger:

# Header text { #anchor-name }

For eksempel kan ankeret for dette afsnit tilpasses til custom-anchors ved hjælp af følgende formatering:

## Custom Markdown anchors { #custom-anchors }

Du kan også oprette et anker på generelt indhold, herunder tekst og kodeblokke. Følgende formatering, med nye linjer ovenfor og nedenfor, skal inkluderes ovenfor det indhold, du ønsker at linke til:

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

Når de brugerdefinerede ankre er oprettet, kan du linke til dem fra det samme dokument eller fra andre dele af dokumentationen.

Standard Markdown bruges til at linke til et anker i samme fil, som formateres som følger:

[Link text](#anchor-name)

Link til et anker i et separat dokument bruger MkDocs-referencelinkstilen, som er formateret som følger:

[Link text][anchor-name]

API-referencelinks¶

MkDocs-referencelinkning understøtter også krydshenvisninger til API-dokumentation, herunder dokumenterede klasser, klassemetoder eller attributter og specifikke eksterne dokumentationshenvisninger.

Der er flere muligheder for at linke til en dokumenteret klasse, en klassemetode eller et klasseattribut, uanset om du linker fra samme fil eller en separat fil. Når du linker til klasser osv., skal du inkludere backticks i det første sæt firkantede parenteser for at gengive navnet som indbygget kode. Backticks er kun unødvendige, hvis du bruger brugerdefineret tekst, der ikke skal gengives som indbygget kode. Backticks bør aldrig inkluderes i det andet sæt firkantede parenteser.

Link til en klasse, mens navneområdet vises, formateres som følger:

[`module.ClassName`][]

Link til en klasse, hvor kun klassens navn vises, formateres som følger:

[`ClassName`][module.ClassName]

Attributterne er de samme som ovenfor, med attributnavnet inkluderet. Følgende viser navneområdet:

[`module.ClassName.attributename`][]

Som med klasser formateres visning af kun attributnavnet som følger:

[`attributename`][module.ClassName.attributename]

Metoder skal vises med () efter navneområdet og skal derfor håndteres anderledes end attributter. Følgende er den korrekte måde at linke til en metode på:

[`module.ClassName.methodname()`][module.ClassName.methodname]

Følgende viser kun klasse- og metodens navn. Dette kræver også, at parenteserne efter navnet medtages:

[`Classname.methodname()`][module.Classname.methodname]

Du kan linke til en klasse, metode eller attribut, mens du viser vilkårlig tekst, ved at bruge den samme metode med det relevante navnerum. Dette gøres med en klasse som følger:

[link text][module.ClassName]

Det er også muligt at linke direkte til Python-kernedokumentationen samt Pillow-dokumentationen. For eksempel for at linke til dokumentationen for int:

[`int`][]

For at linke til dokumentationen for Pillow Image:

[`PIL.Image.Image`][]

Tips til kodeblokke¶

Sprog og kodefremhævning¶

Du kan angive sproget for koden i kodeblokken ved at indsætte sprognavnet efter de første tre backticks uden mellemrum. Dette resulterer i korrekt fremhævning af koden, når den vises. For eksempel skal du starte kodeblokken med ```python for at angive Python.

Konsolkommandoer og kopieringsknappen¶

Hvis du inkluderer konsolkommandoer eller kommandoer med output, skal du mærke dem med console eller doscon, afhængigt af om du beskriver et Unix-lignende operativsystem (inklusive macOS) eller Windows. Du kan inkludere den prompt, der leveres af operativsystemet; kun kommandoen kopieres, når du klikker på kopieringsknappen. Hvis du f.eks. starter et kodeblok med ```console og inkluderer følgende indhold:

$ mkdir test
$ ls
test

Hvis du klikker på kopieringsknappen i kodeblokken, kopieres kun kommandoerne, og prompten og outputtet ignoreres. På denne måde kan du angive, at der er tale om konsolkommandoer, samtidig med at brugerne stadig kan bruge kopieringsknappen effektivt.

Fremhævning af bestemte kodelinjer¶

Du kan fremhæve bestemte kodelinjer. For eksempel, for at fremhæve linje 2, skal du tilføje et mellemrum efter sproget, efterfulgt af {hl_lines="2"}. Så din kodeblok vil begynde med ```python {hl_lines="2"}. Resultatet er:

import toga
from toga.style.pack import COLUMN, ROW

Du kan fremhæve flere forskellige linjer. For eksempel vil python {hl_lines="3 5 9"} fremhæve linjerne 3, 5 og 9. Du kan også fremhæve et interval af linjer. For eksempel fremhæver python {hl_lines="3-8"} linjerne 3 til 8. Du kan fremhæve flere intervaller med for eksempel python {hl_lines="9-18 23-44"}.

Markdown-elementer, der kræver specifik formatering¶

På grund af den måde, oversættelsesfilerne genereres på, er det vigtigt at inkludere de nødvendige nye linjer i Markdown-syntaksen for advarsler, noter, faner, Jinja-direktiver, billedtekster og justering osv.

Advarsler og bemærkninger¶

Advarsler skal formateres som følger, herunder sikre en ny linje før og efter advarslens start og slutning:

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

Dette fungerer på samme måde med alle understøttede advarselstyper. For eksempel kræver noteadvarsler den samme formatering og nye linjer:

Content above.

/// note | Note title

Note text here.

///

Content below.

Alle understøttede advarselstyper kan bruges som advarsler.

Indhold med faner¶

Indhold med faner formateres som følger, inklusive en ny linje før starten og efter slutningen af indholdsblokken:

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

En fane med en indlejret advarsel vil blive formateret som følger, inklusive en ny linje før og efter indholdsblokken:

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

Sammenklappet indhold¶

Sammenklappet indhold formateres som følger, inklusive nye linjer:

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

Alle understøttede advarselstyper kan bruges med sammenklappet indhold, men du skal angive dem som details-admonitiontype. Så en sammenklappet blok af typen "note" vil være details-note (som vist ovenfor), en sammenklappet blok af typen "warning" vil være details-warning, og så videre.

Jinja-direktiver¶

Der er nogle få funktioner i dokumentationen, der bruger Jinja-direktiver i teksten. Alt, der bruger Jinja-direktivfunktionerne, skal indsættes i nye linjer. For eksempel indeholder BeeWare-vejledningen Jinja-betingelser baseret på variabler for at bestemme, hvilken advarsel der skal vises på hovedsiden. Disse er formateret som følger:

Content above.



Content below.

Der findes også en syntaks til erstatning af symboler eller tekst. Denne syntaks er en variabel indrammet af et par matchende dobbelte krøllede parenteser, og hvis den står på sin egen linje, skal den indeholde en ny linje før og efter.

Content above.

{{ variable }}

Content below.

Billedformatering¶

Billeder kan have en fast bredde og kan justeres til venstre, højre og midten (med et forbehold for "midten"). Billeder skal altid indeholde meningsfuld alternativ tekst af hensyn til tilgængeligheden.

Indstilling af bredden på 300px på et billede vil blive formateret som følger:

![Image alt text](../path/to/image.png){ width="300px" }

Justering af et billede til venstre (eller højre) formateres som følger:

![Image alt text](../path/to/image.png){ align=left }

Hvis du vil tilføje en billedtekst til et billede, skal du indsætte en ny linje før og efter billedet og formatere det som følger:

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

Det er ikke muligt at centrere et billede med attributten align. Løsningen er at følge billedet med en tom billedtekst, så bliver det centreret. Du skal indsætte nye linjer mellem hver sektion og før og efter. Det formateres som følger:

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

Plugins med specifik Markdown-formatering¶

De følgende afsnit beskriver, hvordan man bruger plugins, der kræver specifik Markdown-formatering.

Brug af uddrag til at inkludere eksternt indhold¶

For detaljer om, hvordan du inkluderer eksternt indhold fra en lokal fil eller en URL, se Snippets-udvidelsesdokumentationen. Snippets bør bruges, så længe dokumentet ikke indeholder Jinja-direktiver, der skal udføres (Jinja-udførelsen sker sideløbende med Snippets-behandlingen, og derfor vil Jinja i filen ikke blive behandlet). Snippets er nødvendigt, hvis du vil kunne bruge afgrænsere, der giver dig mulighed for at inkludere bestemte dele af en fil separat, f.eks. hvis kildedokumentet er opdelt i sektioner, der skal indsættes separat fra hinanden.

Vigtige bemærkninger:

Vi bruger -8<- som Snippets-identifikator. Dokumentationen viser flere muligheder; følg venligst vores stil.
Filer, der findes i BeeWare Docs Tools-delt indhold, behandles som "lokalt" indhold. Derfor skal du enten kun bruge filnavnet, som i -8<- "docs-style-guide.md", eller, hvis indholdet findes i en undermappe, kun mappen og filnavnet, som i -8<- "style/docs-style-guide.md".
Hvis du inkluderer eksternt indhold fra en fil på GitHub via en URL, skal du bruge den rå indholds-URL, ellers vil hele websiden blive indlejret, uanset hvor du inkluderer den.

Brug af makroer til at inkludere indhold fra BeeWare Docs Tools delt indhold¶

Du kan også inkludere indhold fra BeeWare Docs-værktøjernes delte indholdsmappe ved hjælp af Macros MkDocs-plugin. Denne metode er nødvendig, hvis dokumentet indeholder Jinja-direktiver, der skal udføres, og bør kun bruges i denne situation. Den fungerer ikke med eksternt indhold via en URL. Macros-variabeludskiftningsmekanismen fungerer med denne metode.

Der er muligheder for at inkludere indhold ved hjælp af makroer:

Brug Jinja-syntaksen include, hvis du vil inkludere dokumentet uden andre manuelle ændringer.
Brug Jinja-syntaksen extends, hvis du har inkluderet Jinja block -syntaksen i dokumentet, hvilket giver dig mulighed for at overskrive eller tilføje til bestemte afsnit.

`pyspelling`¶

Vi bruger stavekontrollen pyspelling. Den køres under lint-kontrollen.

Når pyspelling identificerer et forkert stavet ord, skal det i de fleste tilfælde rettes i dokumentationsindholdet.

I det sjældne tilfælde, at det identificerer et gyldigt ord, der ikke findes i pyspelling ordbogen, har du to muligheder:

Hvis det er et ord, der sandsynligvis vil blive genbrugt flere gange, bør du tilføje ordet til spelling_wordlist dokumentet i docs mappen, i alfabetisk rækkefølge.
Hvis det er et ord, der sandsynligvis ikke vil blive brugt igen, kan du indsætte det i en <nospell> / </nospell> tag, og pyspelling vil ignorere det inline.