Kako nastaviti Sphinx za dokumentiranje vaše kode Python

Sphinx je eno najbolj priljubljenih orodij za ustvarjanje dokumentacije. V vsej skupnosti Python razvijalci uporabljajo to brezplačno in odprtokodno programsko opremo. Besedilo lahko izvleče neposredno iz vaše kode ali datotek markdown in ga nato uporabi za ustvarjanje dokumentacije v različnih formatih, kot so golo besedilo, HTML, PDF in EPUB.

Postavitev Sphinx

Preden nastavite Sphinx, si oglejte, kaj počne in nekaj njegovih glavnih funkcij.

Kaj je Sphinx in kaj počne?

Kot že omenjeno, je Sphinx generator dokumentacije. Privzeto uporablja označevalni jezik reStructuredText (RST), prek razširitev tretjih oseb pa lahko uporabite Markdown, priljubljen jezik za označevanje navadnega besedila. Nato te datoteke RST ali markdown pretvori v HTML, PDF, strani priročnika ali druge formate, ki jih želite.

Nekatere funkcije, ki jih vključuje Sphinx, so:

• Sposobnost ustvarjanja dokumentacije iz kode.
instagram viewer
• Zmožnost navzkrižnega sklicevanja na različne strani dokumenta z uporabo samodejnih povezav za funkcije, razrede, citate in izraze v glosarju.
• Označevanje sintakse za bloke kode.
• Podpora za teme, ki lahko spremenijo videz in občutek dokumentov.
• Preprosta definicija drevesa dokumentov prek kazala vsebine.
• Možnost integracije z razširitvami tretjih oseb za dodajanje več funkcionalnosti dokumentom, kot je testiranje odrezkov kode.

Namestitev Sphinx

Preden namestite Sphinx, se prepričajte, da imate Python 3 je nameščen v vašem razvojnem okolju. Nato lahko z upraviteljem paketov pip namestite Sphinx tako, da v terminalu zaženete naslednji ukaz:

pip namestite sfingo

S tem boste prenesli in namestili Sphinx in njegove odvisnosti.

Po namestitvi v ukazni vrstici zaženite naslednje.

sphinx-build --verzija

Če je vse delovalo v redu, bi morali videti številko različice paketa Sphinx, ki ste ga pravkar namestili.

Ustvarjanje novega projekta Sphinx

Ko namestite Sphinx, se pomaknite do svojega delovnega imenika in zaženite ukaz sphinx-quickstart, da ustvarite nov projekt Sphinx.

sfinga-hitri zagon

Ta ukaz vas bo pozval, da odgovorite na vrsto vprašanj o tem, kako konfigurirati vaš projekt Sphinx. Določite lahko ime projekta in uporabite privzete možnosti za druga vprašanja. V prihodnosti boste morda želeli prilagoditi odgovore glede na svoj projekt.

Če izpišete vsebino svojega imenika, boste videli, da ta ukaz za vas ustvari nekaj datotek. Conf.py vsebuje konfiguracijske vrednosti in index.rst služi kot pozdravna stran vaše dokumentacije. Gradbeni imenik bo gostil ustvarjeno dokumentacijo, Sphinx pa uporablja Makefile (make.bat v sistemu Windows) za gradnjo dokumentacije.

Pisanje dokumentacije z uporabo Sphinxa

Datoteka index.rst v korenu vašega imenika je domača stran vaše aplikacije. Torej ga odprite z urejevalnikom besedil, kot je VS Code—ali kateri koli drug dober, brezplačen urejevalnik kode- da ga uredite.

Index.rst lahko spremenite, kot se vam zdi primerno, toda ena stvar, ki bi jo moral imeti, je direktiva root toctree (drevo kazala vsebine). To je bistveno, saj povezuje več datotek v eno samo hierarhijo dokumentov.

Če želite dodati dokumentacijo v datoteko index.rst, lahko uporabite oznako RST.

Kot primer razmislite o datoteki index.rst za modul math_utils. Ta datoteka lahko vključuje kratek pregled namena modula in kazalo vsebine, ki se povezuje na druge strani dokumentacije.

Dobrodošli v Math Utils
.. toctree::
 :maxdepth: 2
Kako začeti

Za uporabo tega modula boste potrebovali naslednje:
* Nameščen Python.
* Urejevalnik besedil
Matematični pripomočki

Modul `math-utils` ponuja osnovne matematične funkcije, kot sta seštevanje in
odštevanje.

Po potrebi lahko dodate več datotek .rst. Ustvarite lahko na primer vodnik za prispevke v datoteki z imenom contributing.rst, ki vsebuje naslednje smernice za prispevke.

Vodnik za prispevke
Veseli bomo prispevkov k našemu projektu! Tukaj je nekaj smernic za
prispevajo:
- Razcepite projekt na GitHub.
- Naredite svoje spremembe na novi veji.
- Napišite teste, da zagotovite, da vaše spremembe delujejo pravilno.
- Predložite zahtevo za vlečenje s svojimi spremembami.
- Izvedite vse zahtevane spremembe.
Hvala za prispevek!

Nato lahko povežete to datoteko iz index.rst tako, da dodate nov razdelek v direktivo toctree:

.. toctree::
 :maxdepth: 2
 :caption: Kazalo

 prispevanje

To ustvari nov element z imenom prispevanje v kazalu vsebine, ki uporabnika po kliku pripelje na stran s prispevki.

Ko napišete dokumentacijo, je naslednji korak njena sestava. Tukaj izdelava dokumentacije pomeni ustvarjanje strani HTML, priročnika ali PDF iz datotek RST.

Gradnja dokumentacije

Če želite zgraditi dokumentacijo s Sphinxom, boste morali zagnati ukaz make html v korenu vaše mape, kjer se nahaja makefile.

naredi html

Videti bi morali datoteke HTML v mapi gradnje. Če je med gradnjo prišlo do napak, vas bo Sphinx obvestil v terminalu.

Za ogled dokumentacije odprite datoteko index.html v brskalniku:

Iz kazala bi morali imeti možnost krmarjenja do vodnika za prispevanje.

Prilagajanje dokumentacije

Trenutno ima dokumentacija nekaj osnovnega stila. Če ga želite prilagoditi, morda z dodajanjem barv vaše blagovne znamke ali celo z dodajanjem temnega načina, lahko namestite in uporabljate druge vgrajene teme ali ustvarite svojo temo po meri.

Za prikaz poskusite spremeniti temo v tisto, ki se imenuje narava:

1. Odprite konfiguracijsko datoteko Sphinx conf.py v vašem imeniku projekta Sphinx.
2. Poiščite vrstico, ki definira možnost html_theme, in jo spremenite v naravo
3. Shranite konfiguracijsko datoteko in znova sestavite dokumentacijo, da vidite svoje spremembe.

Takole bi morala izgledati domača stran dokumentacije.

Če ne želite uporabljati vgrajenih tem, lahko vedno uporabite a tema tretje osebe Sphinx namesto tega.

Dokumentiranje vaše kode z uporabo nizov dokumentov

Sphinx ustvari vašo dokumentacijo Python iz besedila, ki ga napišete v datotekah RST. Čeprav je to v nekaterih primerih dovolj, boste morda želeli uporabiti nize dokumentov v svoji kodi na ravni modula.

Nizi dokumentov živijo neposredno v izvornih datotekah vašega projekta. Omogočajo vam, da opišete, kaj počne koda, zagotovite primere in celo ustvarite teste za te primere. Ko napišete nize dokumentov, lahko iz njih ustvarite dokumentacijo z uporabo Sphinxa.