Få ut det mesta av ditt projekts dokument – ​​använd Sphinx för att skapa attraktiv, omfattande HTML-dokumentation.

Sphinx är ett av de mest populära verktygen för att generera dokumentation. Över hela Python-communityt använder utvecklare denna gratis programvara med öppen källkod. Den kan extrahera text direkt från din kod eller markdown-filer och sedan använda den för att generera dokumentation i olika format som vanlig text, HTML, PDF och EPUB.

Ställa in Sphinx

Innan du ställer in Sphinx, ta en titt på vad den gör och några av dess huvudfunktioner.

Vad är Sphinx och vad gör det?

Som nämnts är Sphinx en dokumentationsgenerator. Som standard använder den märkningsspråket reStructuredText (RST), men genom tillägg från tredje part kan den också använd Markdown, det populära märkningsspråket för vanlig text. Den konverterar sedan dessa RST- eller markdown-filer till HTML, PDF, manuella sidor eller andra format du föredrar.

Några av funktionerna som Sphinx inkluderar är:

  • Möjlighet att generera dokumentation från kod.
    • instagram viewer
  • Möjlighet att korsreferera olika dokumentsidor med hjälp av automatiska länkar för funktioner, klasser, hänvisningar och ordlista.
  • Syntaxmarkering för kodblock.
  • Stöd för teman som kan ändra utseendet och känslan för dokumenten.
  • Enkel definition av dokumentträdet genom en innehållsförteckning.
  • Möjlighet att integrera med tredjepartstillägg för att lägga till mer funktionalitet till dokumenten, som att testa kodavsnitt.

Installera Sphinx

Innan du installerar Sphinx, se till att du har Python 3 installerat i din utvecklingsmiljö. Du kan sedan använda pip-pakethanteraren för att installera Sphinx genom att köra följande kommando i din terminal:

pip installera sfinx

Detta kommer att ladda ner och installera Sphinx och dess beroenden.

Efter installationen, kör följande på kommandotolken.

sphinx-build --version

Om allt fungerade bra bör du se versionsnumret för Sphinx-paketet du just installerade.

Skapa ett nytt sfinxprojekt

När du har installerat Sphinx, navigera till din arbetskatalog och kör kommandot sphinx-quickstart för att skapa ett nytt Sphinx-projekt.

sfinx-snabbstart

Detta kommando kommer att uppmana dig att svara på en rad frågor om hur du konfigurerar ditt Sphinx-projekt. Du kan ange projektnamnet och använda standardalternativen för de andra frågorna. I framtiden kanske du vill anpassa svaren baserat på ditt projekt.

Om du listar innehållet i din katalog kommer du att se att det här kommandot skapar några filer åt dig. Conf.py innehåller konfigurationsvärdena och index.rst fungerar som välkomstsidan för din dokumentation. Byggkatalogen kommer att vara värd för den genererade dokumentationen och Sphinx använder en Makefile (make.bat på Windows) för att bygga dokumentationen.

Skriva dokumentation med Sphinx

Filen index.rst i roten av din katalog är startsidan för din applikation. Så öppna den med en textredigerare som VS Code—eller någon annan bra, gratis kodredigerare– för att redigera den.

Du kan ändra index.rst som du tycker är lämpligt, men en sak som den åtminstone borde ha är direktivet rot toctree (innehållsförteckningsträdet). Detta är viktigt eftersom det kopplar flera filer till en enda hierarki av dokument.

För att lägga till dokumentation till filen index.rst kan du använda RST-markeringen.

Som ett exempel, betrakta en index.rst-fil för modulen math_utils. Den här filen kan innehålla en kort översikt över modulens syfte och en innehållsförteckning som länkar till andra sidor i dokumentationen.

Välkommen till Math Utils
.. toctree::
 :maxdjup: 2


Komma igång


För att använda den här modulen behöver du följande:


* Python installerat.


* En textredigerare


Math Utils


Modulen `math-utils` tillhandahåller grundläggande matematiska funktioner som addition och
subtraktion.

Du kan lägga till fler .rst-filer efter behov. Du kan till exempel skapa en bidragsguide i en fil med namnet contributing.rst som innehåller följande bidragsriktlinjer.

Bidragande guide
Vi välkomnar bidrag till vårt projekt! Här är några riktlinjer för
bidrar med:


- Dela projektet på GitHub.
- Gör dina ändringar på en ny gren.
- Skriv tester för att säkerställa att dina ändringar fungerar korrekt.
- Skicka en pull-begäran med dina ändringar.
- Gör eventuella begärda ändringar.
Tack för att du bidrar!

Du kan sedan länka den här filen från index.rst genom att lägga till ett nytt avsnitt i toctree-direktivet:

.. toctree::
 :maxdjup: 2
 :caption: Innehållsförteckning

 bidrar

Detta skapar ett nytt objekt med namnet bidra i innehållsförteckningen som tar användaren till bidragssidan när den klickas.

När du har skrivit dokumentationen är nästa steg att bygga den. Här innebär att bygga dokumentationen att generera HTML-, manual- eller PDF-sidor från RST-filerna.

Bygga dokumentationen

För att bygga dokumentationen med Sphinx måste du köra kommandot make html i roten av din mapp där makefilen finns.

gör html

Du bör se HTML-filerna i build-mappen. Om det uppstod fel under bygget kommer Sphinx att meddela dig i terminalen.

För att se dokumentationen, öppna filen index.html i din webbläsare:

Du bör kunna navigera till den bidragande guiden från innehållsförteckningen.

Anpassa dokumentationen

Just nu har dokumentationen lite grundläggande styling. Om du vill anpassa det, kanske genom att lägga till dina varumärkesfärger, eller till och med lägga till ett mörkt läge, kan du installera och använda andra inbyggda teman eller skapa ditt eget anpassade tema.

För att demonstrera, försök att ändra temat till det som kallas natur:

  1. Öppna Sphinx-konfigurationsfilen conf.py i din Sphinx-projektkatalog.
  2. Leta efter raden som definierar alternativet html_theme och ändra det till natur
  3. Spara konfigurationsfilen och bygg om dokumentationen för att se dina ändringar.

Så här ska hemsidan för dokumentationen se ut.

Om du inte vill använda de inbyggda teman kan du alltid använda en Sphinx-tema från tredje part istället.

Dokumentera din kod med hjälp av Docstrings

Sphinx genererar din Python-dokumentation från text du skriver i RST-filer. Även om detta är tillräckligt i vissa fall, kanske du också vill använda docstrings i din kod till den på modulnivå.

Docstrings lever direkt inuti ditt projekts källfiler. De låter dig beskriva vad koden gör, ge exempel och till och med skapa tester för dessa exempel. När du har skrivit docstrings kan du generera dokumentation från dem med Sphinx.