Ota kaikki irti projektisi asiakirjoista – käytä Sphinxiä houkuttelevan ja kattavan HTML-dokumentaation luomiseen.

Sphinx on yksi suosituimmista työkaluista dokumentaation luomiseen. Python-yhteisössä kehittäjät käyttävät tätä ilmaista ja avoimen lähdekoodin ohjelmistoa. Se voi poimia tekstiä suoraan koodi- tai merkintätiedostoistasi ja käyttää sitä dokumenttien luomiseen eri muodoissa, kuten pelkkä teksti, HTML, PDF ja EPUB.

Sfinksin asettaminen

Ennen kuin määrität Sphinxin, katso, mitä se tekee ja joitain sen pääominaisuuksia.

Mikä on sfinksi ja mitä se tekee?

Kuten mainittiin, Sphinx on dokumentaatiogeneraattori. Oletuksena se käyttää reStructuredText (RST) -kuvauskieltä, mutta kolmannen osapuolen laajennusten kautta se voi myös käytä Markdownia, suosittua pelkkää tekstinkuvauskieltä. Sitten se muuntaa nämä RST- tai markdown-tiedostot HTML-, PDF-, manuaalisivuiksi tai muihin haluamiisi muotoihin.

Jotkut Sphinxin ominaisuuksista ovat:

  • Kyky luoda dokumentaatiota koodista.
  • Mahdollisuus viitata eri asiakirjasivuihin käyttämällä automaattisia linkkejä funktioille, luokille, lainauksille ja sanastotermeille.
    instagram viewer
  • Koodilohkojen syntaksin korostus.
  • Tuki teemoille, jotka voivat muuttaa asiakirjojen ulkoasua ja tuntumaa.
  • Dokumenttipuun helppo määritellä sisällysluettelon avulla.
  • Mahdollisuus integroida kolmannen osapuolen laajennuksiin lisätoimintojen, kuten koodinpätkien testaamisen, lisäämiseksi asiakirjoihin.

Sphinxin asennus

Ennen kuin asennat Sphinxin, varmista, että sinulla on Python 3 asennettuna kehitysympäristöösi. Voit sitten käyttää pip-pakettien hallintaa asentaaksesi Sphinxin suorittamalla seuraavan komennon päätteessäsi:

pip install sfinksi

Tämä lataa ja asentaa Sphinxin ja sen riippuvuudet.

Suorita asennuksen jälkeen seuraava komentokehotteessa.

sphinx-build --versio

Jos kaikki toimi hyvin, sinun pitäisi nähdä juuri asentamasi Sphinx-paketin versionumero.

Uuden sfinksiprojektin luominen

Kun olet asentanut Sphinxin, siirry työhakemistoosi ja luo uusi Sphinx-projekti suorittamalla sphinx-quickstart-komento.

sfinksi-pikakäynnistys

Tämä komento kehottaa sinua vastaamaan joukkoon kysymyksiä Sphinx-projektin määrittämisestä. Voit määrittää projektin nimen ja käyttää oletusasetuksia muihin kysymyksiin. Jatkossa saatat haluta mukauttaa vastauksia projektisi perusteella.

Jos luet hakemistosi sisällön, näet, että tämä komento luo tiedostoja puolestasi. Conf.py sisältää määritysarvot ja index.rst toimii dokumentaation tervetulosivuna. Rakennushakemisto isännöi luotua dokumentaatiota, ja Sphinx käyttää Makefileä (make.bat Windowsissa) dokumentaation rakentamiseen.

Dokumentaation kirjoittaminen Sphinxillä

Hakemistosi juuressa oleva index.rst-tiedosto on sovelluksesi kotisivu. Joten avaa se tekstieditorilla, kuten VS Code -tai mikä tahansa muu hyvä ilmainen koodieditori– muokata sitä.

Voit muuttaa index.rst-tiedostoa parhaaksi katsomallasi tavalla, mutta yksi asia, jonka siinä ainakin pitäisi olla, on root toctree (sisällysluettelopuu) -direktiivi. Tämä on välttämätöntä, koska se yhdistää useita tiedostoja yhteen asiakirjahierarkiaan.

Voit lisätä dokumentaatiota index.rst-tiedostoon käyttämällä RST-merkintää.

Esimerkkinä voidaan harkita index.rst-tiedostoa math_utils-moduulille. Tämä tiedosto saattaa sisältää lyhyen yleiskatsauksen moduulin tarkoituksesta ja sisällysluettelon, joka linkittää dokumentaation muille sivuille.

Tervetuloa Math Utilsiin
.. toctree::
 :maxsyvyys: 2


Päästä alkuun


Jotta voit käyttää tätä moduulia, tarvitset seuraavat:


* Python asennettu.


* Tekstieditori


Math Utils


"Math-utils" -moduuli tarjoaa perusmatemaattisia toimintoja, kuten yhteenlasku- ja
vähennyslasku.

Voit lisätä .rst-tiedostoja tarpeen mukaan. Voit esimerkiksi luoda osallistumisoppaan tiedostoon nimeltä contributing.rst, joka sisältää seuraavat osallistumisohjeet.

Osallistumisopas
Otamme mielellämme panoksia projektiimme! Tässä on joitain ohjeita
osallistuminen:


- Haaroittele projekti GitHubissa.
- Tee muutokset uudessa haarassa.
- Kirjoita testejä varmistaaksesi, että muutokset toimivat oikein.
- Lähetä muutospyyntösi.
- Tee pyydetyt muutokset.
Kiitos osallistumisestasi!

Voit sitten linkittää tämän tiedoston index.rst: stä ​​lisäämällä uuden osion toctree-direktiiviin:

.. toctree::
 :maxsyvyys: 2
 :caption: Sisällysluettelo

 myötävaikuttaa

Tämä luo sisällysluetteloon uuden kohteen nimeltä Contributing, joka vie käyttäjän osallistumissivulle, kun sitä napsautetaan.

Kun olet kirjoittanut dokumentaation, seuraava vaihe on sen rakentaminen. Tässä dokumentaation rakentaminen tarkoittaa HTML-, manuaalisten tai PDF-sivujen luomista RST-tiedostoista.

Dokumentaation rakentaminen

Luodaksesi dokumentaation Sphinxillä, sinun on suoritettava make html -komento sen kansion juuressa, jossa makefile sijaitsee.

tee html

Sinun pitäisi nähdä HTML-tiedostot build-kansiossa. Jos rakentamisen aikana tapahtui virheitä, Sphinx ilmoittaa siitä terminaalissa.

Katso dokumentaatio avaamalla index.html-tiedosto selaimessasi:

Sinun pitäisi pystyä navigoimaan osallistujaoppaaseen sisällysluettelosta.

Dokumentaation mukauttaminen

Tällä hetkellä dokumentaatiossa on perustyyliä. Jos haluat mukauttaa sitä lisäämällä merkkivärejäsi tai jopa lisäämällä tumman tilan, voit asentaa ja käyttää muita sisäänrakennettuja teemoja tai luo oma mukautettu teema.

Havainnollistaaksesi, kokeile vaihtaa teemaksi luonto:

  1. Avaa Sphinx-määritystiedosto conf.py Sphinx-projektihakemistosta.
  2. Etsi rivi, joka määrittää html_theme-vaihtoehdon, ja muuta se luontoon
  3. Tallenna asetustiedosto ja rakenna dokumentaatio uudelleen nähdäksesi muutokset.

Tältä dokumentaation kotisivun tulee näyttää.

Jos et halua käyttää sisäänrakennettuja teemoja, voit aina käyttää a kolmannen osapuolen Sfinksi-teema sen sijaan.

Koodisi dokumentointi dokumenttimerkkijonojen avulla

Sphinx luo Python-dokumentaatiosi RST-tiedostoihin kirjoittamastasi tekstistä. Vaikka tämä riittää joissakin tapauksissa, saatat haluta myös käyttää dokumenttimerkkijonoja koodissasi siihen moduulitasolla.

Dokumenttimerkkijonot sijaitsevat suoraan projektisi lähdetiedostoissa. Niiden avulla voit kuvailla, mitä koodi tekee, tarjota esimerkkejä ja jopa luoda testejä näille esimerkeille. Kun olet kirjoittanut dokumenttimerkkijonot, voit luoda niistä dokumentteja Sphinxin avulla.