tässä artikkelissa käymme läpi (hyvin) perusteet docstringien dokumentoinnin tuottamiseksi Python-koodiisi. Se on hieman jauhaa, mutta kun teet sen kerran, se on helppo toistaa prosessi jokaisessa uudessa projektissa.

meidän tarkoituksiamme varten oletamme, että (1) uskot koodisi dokumentoinnin arvoon, (2) haluat luoda dokumentteja dokumenteistasi ja (3) Olet päättänyt käyttää sfinksiä työn suorittamiseen.

lopuksi oletetaan, että olet jo asettanut sovelluksellesi erillisen virtuaaliympäristön. Kiinnostuneille pidän todella pyenvin ympäristöpäälliköstä. Siinä on jopa kätevä asentaja.

sinun täytyy asentaa sphinx kautta pip. Vähintään tarvitset version 1.3, mutta ellei sinulla ole hyvää syytä, sinun pitäisi asentaa uusin versio.

$ pip install sphinx

Vaihe 2: Aseta projektisi Quickstart-ohjelmalla

kun asennat sphinx-paketin, myös joukko komentorivin apuohjelmia on asetettu.

yksi niistä, sphinx-quickstart luo nopeasti perusasetustiedoston ja hakemistorakenteen dokumentaatiollesi.

suorita tämä komento projektisi perushakemistossa (eli Git repo-juuressa). Se kysyy useita kysymyksiä, jotka määrittävät sen toimia. Voit yleensä hyväksyä oletusarvot, mutta tässä muutamia ehdotuksia siitä, milloin poikkeat oletuksesta:

kun ohjelma on suoritettu, huomaat, että projektihakemistossasi on uusi ./docs – kansio. Lisäksi kansiossa on kolme uutta tiedostoa: conf.pyindex.rst jaMakefile.

Vaihe 3: säätäminen conf.py tiedosto

oletus conf.py QuickStart-apuohjelman tuottama tiedosto on noin 170 riviä pitkä, joten en sisällytä tähän koko juttua. On kuitenkin, pari kohdetta, jotka meidän täytyy päivittää ennen jatkamista.

kerro Sphinxille Python-pakettisi sijainti

ensimmäiseksi tulee ilmoittaa, missä Ohjelmakoodisi sisältävä Python-paketti on suhteessa conf.py – tiedostoon. Jos hakemistorakenne näyttää tältä:

sinun tulee ilmoittaaconf.pytiedostossa, että Sphinxin täytyy mennä ”ylös” yhtä hakemistotasoa löytääksesi python-paketin.

tämän paikka on asetustiedoston ensimmäisen osion lopussa. Juuri ennen General Configuration asetukset, näet tämän:

# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))

Jos sitä ei kommentoitaisi, se osoittaisi, että pakettisi on samassa hakemistossa kuin conf.py tiedosto. Sinun täytyy muuttaa se tähän:

import os
import sys
sys.path.insert(0, os.path.abspath('..'))

lisää ”Napoleon” Sfinx-laajennusten luetteloon, jota käytetään

pois laatikosta, Sfinx ymmärtää vain perinteisellä saneeraustekstillä kirjoitettuja dokstringejä. Jos sinulla on ollut etuoikeus työskennellä tällaisten dokstringien kanssa, tiedät, että niitä on vaikea kirjoittaa eikä lainkaan ihmisystävällistä lukea, kun katsot niitä suoraan lähdekoodista.

Napoleon-laajennuksen avulla Sphinx pystyy ymmärtämään kahdella muulla suositulla formaatilla kirjoitettuja dokstringejä: NumPy ja Google.

meidän tarvitsee vain lisätä sphinx.ext.napoleonextensions luetteloon. Kun olet valmis, sen pitäisi näyttää tältä:

extensions = 

Step 4: Update index.rst

tässä vaiheessa voisimme itse ajaa rakentamisprosessia tuottaaksemme dokumentaatiomme. Mutta se olisi aika pettymys. Tämän me saisimme:

niin paljon kuin haluaisin sfinksin menevän etsimään meille docstringit ja järjestävän ne hienosti ilman sen kummempaa kokoonpanoa, se ei ole aivan niin maagista.

edetäksemme joudumme tekemään pieniä muutoksia index.rst tiedostoon, joka tällä hetkellä näyttää tältä:

aloitetaan hankkiutumalla eroon huipulla olevasta kommentista, joka on pelkkää kohinaa:

nyt, vaikka täällä voisi tehdä vaikka mitä, aiomme rajoittaa itsemme minimiin pitääksemme tämän postauksen jokseenkin kohtuullisen pituisena.

näetkö, että .. toctree:: rivi? Tätä Sfinksi kutsuu direktiiviksi. Meidän on lisättävä AutoDoc-direktiivit index.rst – tiedostoomme, jotta Sphinx tietää, mihin koodiobjekteihin haluamme käyttää autodoc-laajennusta.

lisään Sphinxiin yhden, joka osoittaa, että haluan sen dokumentoivan main.py modulin sisällä my_project paketti:

Vaihe 5: Kirjoita Docstrings

emme käsittele tässä viestissä docstringien kirjoittamista Numpy-tai Google-tyyliin.

tässä on kuitenkin koodi main.py, joka sisältää pari yksinkertaista NumPy-tyylistä dokstringiä, jotka autodoc-direktiivimme poimii:

Vaihe 6: Luo Docs!

nyt on aika niittää työnne palkka. Varmista, että olet ./docs hakemistossa ja suorita seuraava: make html

Jos olet seurannut tähän asti, sinun pitäisi nähdä jotain tällaista:

niin kauan kuin näet tuon kunniakkaan build succeeded viestin lopussa, olet valmis mene katsomaan kaunista luomustasi.

suorita komentorivillä open _build/html/index.html (tai Avaa kyseinen sivu selaimessasi manuaalisesti) ja sinun pitäisi nähdä jotain tällaista:

next steps

olemme juuri raapaisseet tässä pintaa ja yksinkertaisessa dokumentaatiossamme on vielä paljon syyliä.

seuraavassa tätä aihetta käsittelevässä postauksessa syvennymme autodoc-laajennuksen direktiiveihin ja saavutamme paremman kontrollin dokumentaatiomme sisällöstä ja ulkonäöstä.