Få mest mulig ut av prosjektets dokumenter – bruk Sphinx for å generere attraktiv, omfattende HTML-dokumentasjon.

Sphinx er et av de mest populære verktøyene for å generere dokumentasjon. På tvers av Python-fellesskapet bruker utviklere denne gratis programvaren med åpen kildekode. Den kan trekke ut tekst direkte fra koden eller markdown-filer og deretter bruke den til å generere dokumentasjon i ulike formater som ren tekst, HTML, PDF og EPUB.

Sette opp Sphinx

Før du setter opp Sphinx, ta en titt på hva den gjør og noen av hovedfunksjonene.

Hva er Sphinx og hva gjør det?

Som nevnt er Sphinx en dokumentasjonsgenerator. Som standard bruker den reStructuredText (RST) markup language, men gjennom tredjepartsutvidelser kan den også bruk Markdown, det populære markeringsspråket for ren tekst. Den konverterer deretter disse RST- eller markdown-filene til HTML, PDF, manuelle sider eller andre formater du foretrekker.

Noen av funksjonene Sphinx inkluderer:

  • Evne til å generere dokumentasjon fra kode.
    • instagram viewer
  • Evne til å krysshenvise til forskjellige dokumentsider ved å bruke automatiske lenker for funksjoner, klasser, referanser og ordlisteuttrykk.
  • Syntaksutheving for kodeblokker.
  • Støtte for temaer som kan endre utseendet og følelsen til dokumentene.
  • Enkel definisjon av dokumenttreet gjennom en innholdsfortegnelse.
  • Evne til å integrere med tredjepartsutvidelser for å legge til mer funksjonalitet til dokumentene, for eksempel testing av kodebiter.

Installere Sphinx

Før du installerer Sphinx, sørg for at du har Python 3 installert i utviklingsmiljøet ditt. Du kan deretter bruke pip-pakkebehandlingen til å installere Sphinx ved å kjøre følgende kommando i terminalen din:

pip install sfinx

Dette vil laste ned og installere Sphinx og dets avhengigheter.

Etter installasjonen, kjør følgende på ledeteksten.

sphinx-build --versjon

Hvis alt fungerte bra, bør du se versjonsnummeret for Sphinx-pakken du nettopp installerte.

Opprette et nytt Sphinx-prosjekt

Når du har installert Sphinx, naviger til arbeidskatalogen din og kjør sphinx-quickstart-kommandoen for å lage et nytt Sphinx-prosjekt.

sfinx-hurtigstart

Denne kommandoen vil be deg svare på en rekke spørsmål om hvordan du konfigurerer Sphinx-prosjektet. Du kan spesifisere prosjektnavnet og bruke standardalternativene for de andre spørsmålene. I fremtiden kan det være lurt å tilpasse svarene basert på prosjektet ditt.

Hvis du viser innholdet i katalogen din, vil du se at denne kommandoen lager noen filer for deg. Conf.py inneholder konfigurasjonsverdiene og index.rst fungerer som velkomstsiden til dokumentasjonen. Byggkatalogen vil være vert for den genererte dokumentasjonen, og Sphinx bruker en Makefile (make.bat på Windows) for å bygge dokumentasjonen.

Skrive dokumentasjon ved hjelp av Sphinx

index.rst-filen i roten til katalogen din er startsiden til programmet. Så åpne den med et tekstredigeringsprogram som VS Code-eller hvilken som helst annen god, gratis koderedigerer– for å redigere den.

Du kan endre index.rst som det passer deg, men en ting som det i det minste bør ha er roten toctree (innholdsfortegnelsestreet) direktivet. Dette er viktig siden det kobler flere filer til et enkelt hierarki av dokumenter.

For å legge til dokumentasjon til index.rst-filen, kan du bruke RST-markeringen.

Som et eksempel kan du vurdere en index.rst-fil for math_utils-modulen. Denne filen kan inneholde en kort oversikt over modulens formål og en innholdsfortegnelse som linker til andre sider i dokumentasjonen.

Velkommen til Math Utils
.. toctree::
 :maksdybde: 2


Starter


For å bruke denne modulen trenger du følgende:


* Python installert.


* En tekstredigerer


Math Utils


"math-utils"-modulen gir grunnleggende matematiske funksjoner som addisjon og
subtraksjon.

Du kan legge til flere .rst-filer etter behov. Du kan for eksempel lage en bidragsguide i en fil med navnet contributing.rst som inneholder følgende bidragsretningslinjer.

Bidragsveiledning
Vi tar gjerne imot bidrag til prosjektet vårt! Her er noen retningslinjer for
bidrar med:


- Fordel prosjektet på GitHub.
- Gjør endringene dine på en ny gren.
- Skriv tester for å sikre at endringene dine fungerer som de skal.
- Send inn en pull-forespørsel med endringene dine.
- Gjør eventuelle forespurte endringer.
Takk for at du bidrar!

Du kan deretter koble denne filen fra index.rst ved å legge til en ny seksjon i toctree-direktivet:

.. toctree::
 :maksdybde: 2
 :caption: Innholdsfortegnelse

 bidrar

Dette oppretter et nytt element kalt bidra i innholdsfortegnelsen som tar brukeren til bidragssiden når den klikkes.

Når du har skrevet dokumentasjonen, er neste trinn å bygge den. Her betyr å bygge dokumentasjonen å generere HTML-, manual- eller PDF-sider fra RST-filene.

Bygge dokumentasjonen

For å bygge dokumentasjonen med Sphinx, må du kjøre kommandoen make html i roten av mappen din der makefilen er plassert.

lage html

Du bør se HTML-filene i byggemappen. Hvis det var feil under byggingen, vil Sphinx gi deg beskjed i terminalen.

For å se dokumentasjonen, åpne filen index.html i nettleseren din:

Du skal kunne navigere til den bidragende veiledningen fra innholdsfortegnelsen.

Tilpasse dokumentasjonen

Akkurat nå har dokumentasjonen litt grunnleggende styling. Hvis du vil tilpasse den, ved å kanskje legge til merkefargene dine, eller til og med legge til en mørk modus, kan du installere og bruke andre innebygde temaer eller lag ditt eget tilpassede tema.

For å demonstrere, prøv å endre temaet til det som heter natur:

  1. Åpne Sphinx-konfigurasjonsfilen conf.py i Sphinx-prosjektkatalogen.
  2. Se etter linjen som definerer alternativet html_theme og endre det til natur
  3. Lagre konfigurasjonsfilen og bygg dokumentasjonen på nytt for å se endringene dine.

Slik skal hjemmesiden til dokumentasjonen se ut.

Hvis du ikke vil bruke de innebygde temaene, kan du alltid bruke en tredjeparts Sphinx-tema i stedet.

Dokumentere koden din ved hjelp av Docstrings

Sphinx genererer Python-dokumentasjonen din fra tekst du skriver i RST-filer. Selv om dette er nok i noen tilfeller, vil du kanskje også bruke docstrings i koden til den på modulnivå.

Docstrings lever direkte i prosjektets kildefiler. De lar deg beskrive hva koden gjør, gi eksempler og til og med lage tester for disse eksemplene. Når du har skrevet docstrings, kan du generere dokumentasjon fra dem ved hjelp av Sphinx.