Bidra til Dapla-manualen

Sist endret

November 22, 2024

Alle i SSB kan bidra til denne manualen. Endringer må godkjennes av noen i Team Statistikktjenester eller Alex Crozier (akc@ssb.no). Si gjerne i fra at det ligger en PR å se på. Vi trenger bidrag med alt fra språkvask, nye artikler og andre gode initiativer! Har du lyst til å bidra, men er ikke helt sikker på hva du kan bidra med? Ta en titt på issues i GitHub-repoet.

Warning

Denne nettsiden er åpen og hvem som helst kan lese det som er skrevet her. Hold det i tankene når du skriver.

Forutsetninger

Fremgangsmåten

  1. Klone repoet
terminal
git clone https://github.com/statisticsnorway/dapla-manual.git
  1. Lage en ny gren
  2. Gjøre endringen
  3. Kjør følgende og følge lenken for å sjekke at alt ser bra ut på nettsiden:
terminal
quarto preview dapla-manual
  1. Åpne en PR
  2. Be noen å gjennomgå endringen og eventuelt godkjenne den
  3. Merge PRen
  4. Etter et par minutter skal din endring være synlig!

Tittelblock og nyhetsinnlegg

I dapla-manualen har vi noen konvensjoner vi følger. En av de er å lage en title block som det kalles på quarto sin nettside.

Vi ber våre bidragsytere om å lage en lik block med overskrift og datoen artikkelen ble endret. Åpner man filen til denne siden ser det på dette tidspunktet slik ut:

Skjermbilde av tittelblock.
Figur 1: Tittelblock for denne siden.

Manualens egen nyhetssiden skal oppdaters med et innlegg når det kommer nye artikler. Det er ikke nødvendig å lage en sak om at en side har blitt oppdatert, med mindre endringene er omfattende. Nyhetssiden er i Quarto sitt blog-format. Fremgangsmåten er enkel og beskrives i quarto sin artikkel om blogger. Ellers anbefales det å ta en titt på hvordan det gjøres i dapla-manualen. Alex Crozier (akc@ssb.no) er ansvarlig for nyhetssiden og kan kontaktes dersom man trenger hjelp.

Embedded notebooks

Quarto tilbyr å legge ved (embed) notebooks inn i nettsiden. Dette er en fin måte å dele kode og output på. Men det krever at vi tenker gjennom hvor outputen genereres. Siden Dapla-manualen renderes med GitHub-action, så ønsker vi ikke å introdusere kompleksiteten det innebærer å generere output fra kode her. I tillegg er det mange miljø-spesifikke konfigurasjoner som bestemmer hvordan output kan genereres. Derfor anbefaler vi følgende tilnærming når man skal legge ved en notebook til et kapittel:

  1. Logg deg inn i miljøet du ønsker å bruke.
  2. Klone ned repoet til Dapla-manualen.
  3. Opprett en notebook i mappen ./dapla-manual/notebooks/notebook-navn.ipynb
  4. Skriv kode og generer output som du ønsker. Husk å bare bruke data som alle har tilgang til eller de kan generere selv.
  5. Embed output i kapitlet du ønsker iht til denne beskrivelsen
  6. På toppen av notebooken lager du en raw-celle der du skriver:
notebook
---
freeze: true
---
  1. Kjør denne notebooken fra terminalen med kommandoen:
terminal
quarto render ./notebooks/<notebook-navn.ipynb> --execute

Dette sikrer at vi kan se output etter at boken bygges i GitHub Actions. Husk at notebooks ikke blir strippet for output på vanlig måte, slik at kun åpne data skal benyttes.

Spør Team Statistikktjenester eller Alex (akc@ssb.no) om du lurer på noe.