Kuidas seadistada Sphinx oma Pythoni koodi dokumenteerimiseks

Sphinx on üks populaarsemaid tööriistu dokumentide koostamiseks. Kogu Pythoni kogukonnas kasutavad arendajad seda tasuta avatud lähtekoodiga tarkvara. See võib ekstraheerida teksti otse teie koodi- või allahindlusfailidest ja seejärel kasutada seda dokumentide loomiseks erinevates vormingutes, nagu lihttekst, HTML, PDF ja EPUB.

Sfinksi seadistamine

Enne Sphinxi seadistamist vaadake, mida see teeb ja mõningaid selle põhifunktsioone.

Mis on sfinks ja mida see teeb?

Nagu mainitud, on Sphinx dokumentatsiooni generaator. Vaikimisi kasutab see reStructuredText (RST) märgistuskeelt, kuid kolmanda osapoole laienduste kaudu saab see kasutada ka kasutage populaarset lihtteksti märgistuskeelt Markdown. Seejärel teisendab see need RST- või allahindlusfailid HTML-i, PDF-i, manuaalseteks lehtedeks või muudeks teie eelistatud vorminguteks.

Mõned Sphinxi funktsioonid on järgmised:

• Võimalus koodist dokumentatsiooni genereerida.
instagram viewer
• Võimalus viidata erinevatele dokumendilehtedele funktsioonide, klasside, tsitaatide ja sõnastike terminite automaatsete linkide abil.
• Koodiplokkide süntaksi esiletõstmine.
• Teemade tugi, mis võivad muuta dokumentide välimust ja tunnet.
• Dokumendipuu lihtne määratlemine sisukorra kaudu.
• Võimalus integreerida kolmanda osapoole laiendustega, et lisada dokumentidele rohkem funktsioone, näiteks testida koodilõike.

Sphinxi paigaldamine

Enne Sphinxi installimist veenduge, et teil on Teie arenduskeskkonda installitud Python 3. Seejärel saate Sphinxi installimiseks kasutada pip-paketihaldurit, käivitades terminalis järgmise käsu:

pip install sfinks

See laadib alla ja installib Sphinxi ja selle sõltuvused.

Pärast installimist käivitage käsureal järgmine toiming.

sphinx-build --versioon

Kui kõik toimis hästi, peaksite nägema just installitud Sphinxi paketi versiooninumbrit.

Uue Sfinksi projekti loomine

Kui olete Sphinxi installinud, liikuge oma töökataloogi ja käivitage käsk sphinx-quickstart, et luua uus Sphinxi projekt.

sfinks-kiire algus

See käsk palub teil vastata paljudele küsimustele, kuidas oma Sphinxi projekti konfigureerida. Saate määrata projekti nime ja kasutada muude küsimuste puhul vaikevalikuid. Tulevikus võiksite vastuseid oma projekti põhjal kohandada.

Kui loetlete oma kataloogi sisu, näete, et see käsk loob teie jaoks mõned failid. Conf.py sisaldab konfiguratsiooniväärtusi ja index.rst on teie dokumentatsiooni tervitusleht. Ehitamise kataloog majutab loodud dokumentatsiooni ja Sphinx kasutab dokumentatsiooni koostamiseks Makefile'i (Windowsis make.bat).

Dokumentatsiooni kirjutamine Sfinksi abil

Teie kataloogi juures olev fail index.rst on teie rakenduse avaleht. Niisiis, avage see tekstiredaktoriga (nt VS Code) või mõni muu hea tasuta koodiredaktor- seda redigeerida.

Saate muuta index.rst oma äranägemise järgi, kuid üks asi, mis sellel peaks vähemalt olema, on root toctree (sisukorrapuu) direktiiv. See on oluline, kuna see ühendab mitu faili ühte dokumentide hierarhiasse.

Dokumentatsiooni lisamiseks faili index.rst saate kasutada RST-märgistust.

Näiteks kaaluge mooduli math_utils faili index.rst. See fail võib sisaldada lühikest ülevaadet mooduli eesmärgist ja sisukorda, mis viitab dokumentatsiooni teistele lehtedele.

Tere tulemast Math Utilsi
.. toctree::
 :maksimaalne sügavus: 2
Alustamine

Selle mooduli kasutamiseks vajate järgmist.
* Python installitud.
* Tekstiredaktor
Math Utils

Moodul "math-utils" pakub põhilisi matemaatilisi funktsioone, nagu liitmine ja
lahutamine.

Vajadusel saate lisada rohkem .rst-faile. Näiteks saate luua kaastööde juhendi faili nimega contributing.rst, mis sisaldab järgmisi kaastöö juhiseid.

Kaastöö juhend
Ootame panust meie projekti! Siin on mõned juhised
panustades:
- ühendage projekt GitHubis.
- Tehke oma muudatused uues harus.
- Kirjutage teste, et tagada muudatuste korrektne toimimine.
- Esitage oma muudatustega tõmbamistaotlus.
- Tehke soovitud muudatused.
Täname panuse eest!

Seejärel saate selle faili linkida saidilt index.rst, lisades toctree direktiivile uue jaotise:

.. toctree::
 :maksimaalne sügavus: 2
 :pealkiri: Sisukord

 panustades

See loob sisukorras uue üksuse nimega panustamine, mis viib kasutaja klõpsamisel kaastöölehele.

Kui olete dokumentatsiooni kirjutanud, on järgmine samm selle koostamine. Siin tähendab dokumentatsiooni koostamine RST-failidest HTML-, manuaal- või PDF-lehtede genereerimist.

Dokumentatsiooni koostamine

Dokumentatsiooni koostamiseks Sphinxi abil peate käivitama käsu make html selle kausta juurtes, kus makefile asub.

tee html

Peaksite nägema ehituskaustas HTML-faile. Kui ehitamise ajal ilmnes vigu, annab Sphinx teile terminalis teada.

Dokumentatsiooni vaatamiseks avage brauseris fail index.html:

Peaksite suutma navigeerida sisukorrast kaastööjuhendi juurde.

Dokumentatsiooni kohandamine

Praegu on dokumentatsioonil põhiline stiil. Kui soovite seda kohandada, lisades oma brändi värve või isegi lisades tumeda režiimi, saate installida ja kasutada muid sisseehitatud teemad või looge oma kohandatud teema.

Demonstreerimiseks proovige muuta teema teemaks, mida nimetatakse looduseks:

1. Avage oma Sphinxi projekti kataloogis Sphinxi konfiguratsioonifail conf.py.
2. Otsige üles rida, mis määratleb suvandi html_theme, ja muutke see olemuseks
3. Muudatuste nägemiseks salvestage konfiguratsioonifail ja koostage dokumentatsioon uuesti.

Selline peaks välja nägema dokumentatsiooni koduleht.

Kui te ei soovi sisseehitatud teemasid kasutada, võite alati kasutada a kolmanda osapoole sfinksi teema selle asemel.

Koodi dokumenteerimine dokumendistringide abil

Sphinx loob teie Pythoni dokumentatsiooni tekstist, mille kirjutate RST-failidesse. Kuigi mõnel juhul piisab sellest, võite soovida kasutada oma koodis olevaid dokumente ka mooduli tasemel.

Docstringid asuvad otse teie projekti lähtefailides. Need võimaldavad teil kirjeldada, mida kood teeb, tuua näiteid ja isegi luua nende näidete jaoks teste. Kui olete dokumendistringid kirjutanud, saate nendest Sphinxi abil dokumentatsiooni luua.