Yksinkertainen opetusohjelma Python-projektin dokumentoimiseksi käyttämällä Sphinxiä ja Rinohtypeä

Koodin dokumentointi on yksi niistä tehtävistä, jota en todellakaan halua tehdä, mutta teen sen silti arvosanoille.

Tämä on todennäköisesti se, mitä kuulet minulta, kun olin ensimmäisen vuoden tietotekniikan opiskelija. Pidän dokumentointikoodin tylsää ja hyödytöntä, koska tiedän jo koodini ja ainoa henkilö, joka todennäköisesti lukee sen, on professori, joka tarkistaa sen.

En ymmärtänyt sen merkitystä vasta eräänä päivänä, minun piti tarkastella sitä dokumenttimatonta koodia, jonka kirjoitin vuosia sitten viitteeksi, ja sen sijaan, että vain käyisin läpi sitä, vietin paljon aikaa melko hämmentyneenä siitä, kuinka organisoin projektin ja jopa kuinka sitä ajaa.

Nykyään on olemassa paljon työkaluja, jotka auttavat meitä koodin dokumentoinnissa. Äskettäin olen oppinut työkaluista, joiden avulla on helppo luoda älykkäitä ja kauniita dokumentaatioita. Kaksi niistä on Sfinksi ja Rinohtype.

Georgian Brandlin kirjoittama ja BSD-lisenssillä lisensoitu Sphinx on alun perin luotu Python-dokumentaatioon, ja sillä on erinomaiset mahdollisuudet ohjelmistoprojektien dokumentointiin useilla kielillä (Sphinx-doc.org, 2018).

Rinohtype, pariksi Sphinx, tarjoaa modernin vaihtoehdon LaTeX. Se tarjoaa Sphinx-taustajärjestelmän, jonka avulla voidaan tuottaa ammattimaisesti kirjoitettuja PDF-dokumentteja (Machiels).

Tässä opetusohjelmassa aion tuottaa Sphinx- ja Rinohtype -sovelluksia HTML- ja PDF-dokumenttitiedostoihin vastaavaan yksinkertaiseen API-projektiin, jonka kirjoitin ja joka hallinnoi luetteloa Opettajan tietueista (Github Project Link).

  1. Klooni projekti ja poista / siirrä docs-kansio, jotta voit seurata minua luotaessa uutta dokumentaatiota.
  2. Siirry projektin juurihakemistoon.
  3. Luo ja aktivoi Python 3 -ympäristö
virtualenv -p python3 
lähde  / bin / aktivoi
Täällä nimitin virtuaalisen ympäristöni

4. Asenna kaikki projektivaatimukset

pip install -r vaatimukset.txt

Huomaa: Sphinx ja Rinohtype ovat jo vaatimus.txt-tiedoston sisällä. Jos haluat asentaa ne projektisi virtuaaliympäristöön, jonka parissa työskentelet, käytä seuraavia komentoja alla.

pip asentaa Sphinx
pip asentaa rinohtype

5. Luo docs-hakemisto ja cd tähän hakemistoon.

mkdir docs
CD-dokumentit

6. Aseta Sfinksi

sfinksi-quickstart
Seuraa tätä kokoonpanoa nyt. Voit määrittää tämän myöhemmin itse.edellisen kuvan jatko

7. Avoimen lähdekoodin / konf.py

  • Määritä polku juurihakemistoon
Kommentit rivit 15–17Muuta polku kohtaan ../ .. ja lisää sys.setrecursionlimit (1500)

Polun tulisi osoittaa projektin juurihakemistoon ja tarkastella projektin rakennetta, conf.py: stä meidän pitäisi päästä juuriin menemällä ylös kaksi emohakemistoa.

Projektin rakenne
  • Lisää Rinohtype laajennusluetteloon
'Rinoh.frontend.sphinx'
  • Kommentoi lateksielementtejä
kommentoi näitäVoit muuttaa muotoa edelleen, nämä ovat vain oletusasetuksia.

8. Avaa index.rst ja muuta sisältö seuraavaan. (Napsauta index.rst -linkkiä saadaksesi täyden sisällön)

Ohjeen dokumentaatio
**************************
.. toctree ::
   : korkein syvyys: 2
   : kuvateksti: Sisältö:

OpettajaAPI pää
===================
.. auto: :: sovellus
   :jäsenet:

TeacherAPI-ohjain
=====================
..automoduuli :: opettajaAPI.kontrolleri
   :jäsenet:

OpettajaAPI-mallit
=================
..automoduuli :: opettajaAPI.mallit
   :jäsenet:

TeacherAPI-tietokanta
===================
.. autodule :: opettajaAPI.database
   :jäsenet:

OpettajaAPI asuu
===================
..automoduuli :: opettajaAPI.väestö
   :jäsenet:

9. Luo HTML- ja PDF-dokumentaatiotiedostot.

  • Vielä docs-hakemiston ajon sisällä
tee html
sphinx-build -b rinoh lähde _build / rinoh

MUOKKAA HUOMAUTUS [16. maaliskuuta 2019]: pdf-tiedoston luominen epäonnistuu, jos Python-versiosi on ≥3.7.0 (Github-julkaisuviite)

Ensimmäinen rivi tuottaa HTML-tiedoston hakemistossa docs / build / html / index.html

Näkymä hakemistoon.htmlNäkymä hakemistoon.html

Toinen rivi tuottaa PDF-tiedoston docs / _build / rinoh / SimpleTeacherDataAPI.pdf

Asiakirjojen etusivuSisällysluetteloDokumentaation mallisivu

Kokenutani ollaan ryhmäprojekteissa, aloin kehittää tunnustusta koodin dokumentoinnissa, ja vaikka en sanoisi, että se on nautinnollisin tehtävä, se on ehdottomasti luotettava ja ohjelmoijien tulee harjoitella sitä .

Lisätietoja Sphinxistä:

  • Yleiskatsaus - Sphinx 1.8.0+ -dokumentaatio

Muita hyödyllisiä oppaita:

  • Projektin dokumentointi Sphinxillä - Tämä auttoi minua ymmärtämään kuinka dokumentoida koodini Python-ohjeilla.
  • Brandonin Sphinx-opetusohjelma - Laaja opetusohjelma Sphinxin käytöstä

Machiels, Brecht. “Rinohtype: Python-asiakirjan prosessori - Rinohtype 0.3.1.Dev0 -dokumentaatio.” Rinohtype.readthedocs.io. N.p., 2016. Web. 17. kesäkuuta 2018.

Sphinx-doc.org. (2018). Yleiskatsaus - Sphinx 1.8.0+ -dokumentaatio. [verkossa] Saatavana osoitteessa: http://www.sphinx-doc.org/en/master/ [Pääsy 17. kesäkuuta 2018].