Oppgave: Dokumentasjonspublisering

I denne oppgaven skal du bruke prinsippene fra CI/CD for å opprette en GitHub workflow som publiserer dokumentasjon til et programmeringsprosjekt opp mot GitHub pages. Også kjent som Continuous Documentation Deployment.

God dokumentasjon pleier å inneholde følgende:

• Oversikt over prosjektet
• Installasjon
• Bruksinstrukser (kodereferanser / schema)
• Endringslogg (Changelog)
• Lisens
• Credits

Du kan ta utgangspunkt i følgende GitHub repository: (TBD, mangler link)

Hvorfor dokumentasjon?

Fremgangsmåte

For å få mest utbytte av oppgaven anbefales det å følge stegene under.

Det anbefales å bruke mkdocs og Markdown sider for å gjennomføre oppgaven, men det finnes alltid alternativer!

• https://squidfunk.github.io/mkdocs-material/
• https://docs.readthedocs.io/en/stable/index.html

1. Forstå koden

Før man kan skrive dokumentasjon, må man forstå hva formålet bak koden er. Tenk gjennom når du leser koden: Hva, hvorfor og hvordan? Hva gjør koden? Hvorfor ble den skrevet, til hvilket formål? Hvordan kan man ta den i bruk?

2. Konfigurer dokumentasjonstjenesten

Før du skriver dokumentasjon, så kan det være lurt å teste ut noen andre sin dokumentasjon først! Bruk dokumentasjonen til å finne ut hvordan du konfigurerer tjenesten.

Dersom du ønsker å bruke mkdocs, bør du følge dokumentasjonen: https://squidfunk.github.io/mkdocs-material/creating-your-site/

Eller så kan du se den i form av en YouTube tutorial (start fra 3:26, du finner tilsvarende funksjonalitet i PyCharm):

Merk at en YouTube video er ikke alltid like oppdatert, men er ofte enklere å fordøye.

3. Skriv dokumentasjonen

Det kan være lurt å begynne med å skrive tekst i et tekstbehandlingsprogram, eller direkte som en Markdown fil (.md) i utviklingsmiljøet i en egen docs mappe. Dersom dokumentasjonen angår kodens funksjoner eller klasser, vil det være lurt å skrive denne direkte i kodefilene i form av docstrings (se under), eventuelt kommentarer.

Din dokumentasjon bør inneholde følgende:

• index - Oversikt over prosjektet, hva er det?
• Installation - Hvordan installerer man? (Kan være en del av index)
• Usage - Hvordan bruker man? (Kan være en del av index)
• Code Reference - Hvordan fungerer koden? Hva gjør de ulike funksjonene? Se også: https://mkdocstrings.github.io/

Eksempel docstring i kode

Det finnes ulike standarder for docstrings, noen av de mest vanlige er Google og Sphinx sin standard, eller NumPy for mer matematiske prosjekter.

I PyCharm er Sphinx brukt som standard docstringformat, som er brukt i eksemplene under.

Se for deg at vi har følgende kode:

1
2
3
4
5
6
7

def calculate_price(cost: float) -> float:
    total = cost * 1.25

    if total < 500:
        total += 79

    return total

og tenk, hvor enkelt er det å forstå koden?

Her er samme kode med en docstring:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

def calculate_price(cost: float) -> float:
    """
    Calculate the final price of a product, including taxes and shipping costs.
    If the final price is less than 500, a shipping cost of 79 is added.

    :param cost: The net price of the product (without taxes).
    :return: The final price of the product (including taxes and shipping costs).
    """
    total = price * 1.25

    if total < 500:
        total += 79

    return total

Lettere å forstå formålet til koden nå, ikke sant? Merk at koden ville egentlig hatt mer nytte av å brytes opp i mindre funksjoner for å slippe å måtte forklares grundig gjennom en docstring.

1
2

def heal(hp, amnt):
   hp += amnt

1
2

def heal(character: Character, amount_to_heal: int) -> None:
    character.hp += amount_to_heal

4. Opprett en GitHub Workflow

Ved å opprette en Workflow fil (under GitHub Actions) kan man lage instrukser til en GitHub Runner, som spinner opp en virtuell maskin og utfører oppgaver for oss. Workflowene må lagres i en egen mappe i repoet: .github/workflows/ og være i .yml format.

GitHub Actions kan være skremmende til å starte med, men heldigvis kan du benytte deg av forhåndsdefinerte maler, eller ta utgangspunkt i denne filen, det er lagt inn kommentarer der du kan fritt gjøre endringer. Merk at runneren tar utgangspunkt i mkdocs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

name: Documentation

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    permissions:
      contents: write
      pages: write
      id-token: write
    steps:
    - uses: actions/checkout@v3

    - name: Set up Python 3.10
      uses: actions/setup-python@v3
      with:
        python-version: "3.10"

    # HER KAN DU LEGGE TIL EKSTRA LINJER MED
    # LINUX KOMMANDOER, F.EKS. FLYTTE ELLER
    # OPPRETTE NYE FILER (F.EKS.) REDIGERE
    # "Sist oppdatert" TEKST.
    - name: Install Python Packages
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel
        pip install mkdocs
        echo Hello World!

    - name: Build site
      run: mkdocs build --clean

    - name: Upload artifact
      uses: actions/upload-pages-artifact@v1
      with:
        name: github-pages
        path: ./site

    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v1

5. Verifiser GitHub Pages

Inne på GitHub repoet skal du nå finne en Environment fane i menyen, dersom steg 3 var vellykket.

Trykk deg inn på denne for å finne linken til dokumentasjonen din. Fungerer den? Ser noe rart ut?

Dersom alt fungerer, kan du oppdatere repoet til å inkludere en link. Vis derretter dokumentasjonen til en annen og be om tilbakemelding. Er det noe som kan formuleres enklere?

6. Forbedre dokumentasjonen

Dersom du har mer tid, kan du prøve å forbedre dokumentasjonen din etter tilbakemeldingene du har fått.

Du kan også prøve å legge til illustrasjoner, bilder eller annet innhold, the ☁ is the limit!

1 år siden 1 år siden GitHub