Haal het meeste uit de documenten van uw project: gebruik Sphinx om aantrekkelijke, uitgebreide HTML-documentatie te genereren.

Sphinx is een van de meest populaire tools voor het genereren van documentatie. In de hele Python-gemeenschap gebruiken ontwikkelaars deze gratis en open-source software. Het kan tekst rechtstreeks uit uw code of markdown-bestanden extraheren en deze vervolgens gebruiken om documentatie in verschillende indelingen te genereren, zoals platte tekst, HTML, PDF en EPUB.

Sfinx opzetten

Bekijk voordat u Sphinx instelt wat het doet en enkele van de belangrijkste functies.

Wat is Sfinx en wat doet het?

Zoals gezegd is Sphinx een documentatiegenerator. Standaard gebruikt het de opmaaktaal reStructuredText (RST), maar via extensies van derden kan het ook gebruik Markdown, de populaire opmaaktaal voor platte tekst. Vervolgens converteert het deze RST- of markdown-bestanden naar HTML, PDF, manpagina's of andere formaten die u verkiest.

Enkele van de functies die Sphinx bevat, zijn:

instagram viewer
  • Mogelijkheid om documentatie uit code te genereren.
  • Mogelijkheid om te verwijzen naar verschillende documentpagina's met behulp van automatische koppelingen voor functies, klassen, citaten en woordenlijsten.
  • Syntaxisaccentuering voor codeblokken.
  • Ondersteuning voor thema's die het uiterlijk van de documenten kunnen veranderen.
  • Eenvoudige definitie van de documentboom door middel van een inhoudsopgave.
  • Mogelijkheid om te integreren met extensies van derden om meer functionaliteit aan de documenten toe te voegen, zoals het testen van codefragmenten.

Sfinx installeren

Voordat u Sphinx installeert, moet u ervoor zorgen dat u dat hebt gedaan Python 3 geïnstalleerd in uw ontwikkelomgeving. U kunt dan de pip-pakketbeheerder gebruiken om Sphinx te installeren door de volgende opdracht in uw terminal uit te voeren:

pip installeer sfinx

Hiermee worden Sphinx en zijn afhankelijkheden gedownload en geïnstalleerd.

Voer na de installatie het volgende uit op de opdrachtprompt.

sphinx-build --versie

Als alles goed werkte, zou u het versienummer moeten zien van het Sphinx-pakket dat u zojuist hebt geïnstalleerd.

Een nieuw Sphinx-project maken

Nadat u Sphinx hebt geïnstalleerd, navigeert u naar uw werkmap en voert u de opdracht sphinx-quickstart uit om een ​​nieuw Sphinx-project te maken.

sphinx-snelstart

Met deze opdracht wordt u gevraagd een reeks vragen te beantwoorden over het configureren van uw Sphinx-project. U kunt de projectnaam specificeren en de standaardopties gebruiken voor de andere vragen. In de toekomst wilt u misschien de reacties aanpassen op basis van uw project.

Als u de inhoud van uw map opsomt, zult u zien dat deze opdracht enkele bestanden voor u aanmaakt. De conf.py bevat de configuratiewaarden en de index.rst dient als de welkomstpagina van uw documentatie. De build-directory zal de gegenereerde documentatie hosten en Sphinx gebruikt een Makefile (make.bat op Windows) om de documentatie te bouwen.

Documentatie schrijven met Sphinx

Het bestand index.rst in de hoofdmap van uw map is de startpagina van uw toepassing. Dus open het met een teksteditor zoals VS Code - of elke andere goede, gratis code-editor- om het te bewerken.

U kunt de index.rst naar eigen goeddunken wijzigen, maar één ding dat het op zijn minst zou moeten hebben, is de root toctree (inhoudsopgave boom) richtlijn. Dit is essentieel omdat het meerdere bestanden verbindt met een enkele hiërarchie van documenten.

Om documentatie aan het index.rst-bestand toe te voegen, kunt u de RST-opmaak gebruiken.

Neem als voorbeeld een bestand index.rst voor de module math_utils. Dit bestand kan een kort overzicht bevatten van het doel van de module en een inhoudsopgave met koppelingen naar andere pagina's van de documentatie.

Welkom bij Math Utils
.. toctree::
 :maxdiepte: 2


Aan de slag


Om deze module te gebruiken, heb je het volgende nodig:


*Python geïnstalleerd.


* Een teksteditor


Wiskundige toepassingen


De module `math-utils` biedt elementaire wiskundige functies zoals optellen en
aftrekken.

U kunt indien nodig meer .rst-bestanden toevoegen. U kunt bijvoorbeeld een bijdragerichtlijn maken in een bestand met de naam contributie.rst dat de volgende bijdragerichtlijnen bevat.

Bijdragende gids
Wij zijn blij met bijdragen aan ons project! Hier zijn enkele richtlijnen voor
bijdragende:


- Fork het project op GitHub.
- Breng uw wijzigingen aan op een nieuwe tak.
- Tests schrijven om ervoor te zorgen dat uw wijzigingen correct werken.
- Dien een pull-aanvraag in met uw wijzigingen.
- Breng de gevraagde wijzigingen aan.
Bedankt voor je bijdrage!

U kunt dit bestand vervolgens koppelen vanuit index.rst door een nieuwe sectie toe te voegen aan de toctree-richtlijn:

.. toctree::
 :maxdiepte: 2
 :caption: Inhoudsopgave

 bijdragende

Dit creëert een nieuw item met de naam bijdragen in de inhoudsopgave dat de gebruiker naar de bijdragepagina brengt wanneer erop wordt geklikt.

Nadat u de documentatie hebt geschreven, is de volgende stap het bouwen ervan. Hier betekent het bouwen van de documentatie het genereren van HTML-, handleiding- of PDF-pagina's van de RST-bestanden.

Het bouwen van de documentatie

Om de documentatie op te bouwen met behulp van Sphinx, moet u de opdracht make html uitvoeren in de hoofdmap van uw map waar de makefile zich bevindt.

html maken

U zou de HTML-bestanden in de build-map moeten zien. Als er fouten zijn opgetreden tijdens het bouwen, laat Sphinx dit weten in de terminal.

Om de documentatie te bekijken, opent u het bestand index.html in uw browser:

U zou vanuit de inhoudsopgave naar de bijdragende gids moeten kunnen navigeren.

De documentatie aanpassen

Op dit moment heeft de documentatie een aantal basisstijlen. Als u het wilt aanpassen, door misschien uw merkkleuren toe te voegen of zelfs een donkere modus toe te voegen, kunt u andere installeren en gebruiken ingebouwde thema's of maak je eigen aangepaste thema.

Probeer om het te demonstreren het thema te veranderen in het thema dat natuur wordt genoemd:

  1. Open het Sphinx-configuratiebestand conf.py in uw Sphinx-projectdirectory.
  2. Zoek naar de regel die de optie html_theme definieert en wijzig deze in nature
  3. Sla het configuratiebestand op en bouw de documentatie opnieuw op om uw wijzigingen te zien.

Zo zou de homepage van de documentatie eruit moeten zien.

Als u de ingebouwde thema's niet wilt gebruiken, kunt u altijd een Sphinx-thema van derden in plaats van.

Uw code documenteren met behulp van Docstrings

Sphinx genereert uw Python-documentatie op basis van tekst die u in RST-bestanden schrijft. Hoewel dit in sommige gevallen voldoende is, wilt u misschien ook docstrings in uw code gebruiken op moduleniveau.

Docstrings leven rechtstreeks in de bronbestanden van uw project. Ze laten je beschrijven wat de code doet, geven voorbeelden en maken zelfs tests voor die voorbeelden. Nadat u docstrings heeft geschreven, kunt u er documentatie van genereren met behulp van Sphinx.