Lihtne õpetus Pythoni projekti dokumenteerimiseks, kasutades Sphinxit ja Rinohtype'i

Koodi dokumenteerimine on üks neist ülesannetest, mida ma tõesti ei taha teha, kuid teen seda igal juhul klasside jaoks.

Tõenäoliselt kuulete seda minust, kui olin esimese aasta informaatikatudeng. Minu arvates on dokumenteerimiskoodi dokumenteerimine igav ja kasutu, kuna ma juba tean, mida mu kood teeb, ja ainus inimene, kes seda tõenäoliselt luges, on professor, kes seda kontrollib.

Ma ei mõistnud selle olulisust alles ühel päeval, ma pidin vaatama seda dokumenteerimata koodi, mille ma aastaid tagasi viiteks kirjutasin, ja selle asemel, et seda lihtsalt läbi vaadata, veetsin palju aega, olles üsna segaduses projekti struktureerimise osas ja isegi kuidas seda käivitada.

Täna on saadaval palju tööriistu, mis aitavad meil koodi dokumenteerida. Hiljuti sain teada tööriistadest, mis lihtsustavad intelligentse ja ilusa dokumentatsiooni loomist. Neist kaks on Sfinks ja Rinohtype.

Georg Brandli kirjutatud ja BSD litsentsi alusel litsentsitud Sphinx loodi algselt Pythoni dokumentatsiooni jaoks ja sellel on suurepärased võimalused tarkvaraprojektide dokumenteerimiseks erinevates keeltes (Sphinx-doc.org, 2018).

Rinohtype koos Sphinxiga pakub kaasaegset alternatiivi LaTeX-ile. See pakub Sphinxi taustaprogrammi, mis võimaldab genereerida professionaalselt trükitud PDF-dokumente (Machiels).

Selles õpetuses kasutan Sphinxi ja Rinohtype'i HTML-i ja PDF-dokumentide failide tootmiseks vastavalt minu kirjutatud lihtsale API-projektile, mis haldab õpetajate kirjete loetelu (Github Project Link).

  1. Kloonige projekt ja kustutage / teisaldage dokumentide kaust, nii et võite uue dokumentatsiooni loomisel mind jälgida.
  2. Minge projekti juurkataloogi.
  3. Looge ja aktiveerige Python 3 virtuaalne keskkond
virtualenv -p python3 
allikas  / bin / aktiveeri
Nimetasin siin oma virtuaalse keskkonna “venv”

4. Installige kõik projekti nõuded

pip install -r nõuetele.txt

Märkus. Sphinx ja Rinohtype on juba failide.txt failis. Kui soovite neid installida projekti virtuaalsesse keskkonda, mille kallal töötate, kasutage järgmisi allpool toodud käske.

pip install Sphinx
pip install rinohtype

5. Koostage dokumentide kataloog ja CD sellesse kataloogi.

mkdir docs
CD-d

6. Sfinksi seadistamine

sphinx-kiirstart
Järgige seda konfiguratsiooni praegu. Võite selle hiljem ise konfigureerida.eelmise pildi jätk

7. Avatud lähtekoodiga / konf.py

  • Juurkataloogi tee konfigureerimine
Kommenteerimata read 15–17Muutke tee väärtuseks '../ ..' ja lisage sys.setrecursionlimit (1500)

Tee peaks osutama projekti juurkataloogile ja vaadates projekti ülesehitust, siis konf.py-st peaksime juurini jõudma kahe vanema kataloogist ülespoole minnes.

Projekti ülesehitus
  • Lisage laiendi loendisse Rinohtype
'rinoh.frontend.sphinx'
  • Lateksielementide mittekommenteerimine
kommenteerige neidVormingut saate veelgi muuta, need on lihtsalt vaikimisi seadistused.

8. Avage index.rst ja muutke sisu järgmiseks. (Täieliku sisu saamiseks klõpsake linki index.rst)

Koodeksi dokumentatsioon
**************************
.. toctree ::
   : maksimaalne sügavus: 2
   : pealdis: Sisu:

ÕpetajaAPI peamine
===================
.. automodule :: app
   : liikmed:

ÕpetajaAPI kontroller
=====================
.. auto moodul: õpetajaAPI.kontroller
   : liikmed:

ÕpetajaAPI mudelid
=================
.. automood :: õpetajaAPI.mudelid
   : liikmed:

ÕpetajaAPI andmebaas
===================
.. autod :: õpetajaAPI.andmebaas
   : liikmed:

ÕpetajaAPI asustatud
===================
..auto :: õpetajaAPI.rahvastik
   : liikmed:

9. Looge HTML- ja PDF-dokumenteerimisfailid.

  • Ikka dokumentide kataloogis käitamise sees
tee html
sphinx-build -b rinoh source _build / rinoh

MÄRKUS Redigeerimine [16. märts 2019]: pdf-faili koostamine ebaõnnestub, kui teie Pythoni versioon on ≥3.7.0 (Githubi väljaande viide)

Esimene rida loob HTML-faili dokumendis / build / html / index.html

Vaade index.htmlVaade index.html

Teine rida annaks PDF-faili dokumendis docs / _build / rinoh / SimpleTeacherDataAPI.pdf

Dokumentatsiooni tiitellehtSisukordDokumentatsiooni näidisleht

Pärast meeskonnaprojektides osalemist hakkasin kodeerima tunnustust koodide dokumenteerimisel ja kuigi ma ei ütleks, et see on kõige nauditavam ülesanne, on see kindlasti usaldusväärne ja seda peaksid tegema programmeerijad .

Sphinxi kohta lisateabe saamiseks tehke järgmist.

  • Ülevaade - Sphinx 1.8.0+ dokumentatsioon

Muud kasulikud õpetused:

  • Projekti dokumenteerimine Sphinxi abil - see aitas mul mõista, kuidas oma koodi Pythoni dokumentide abil dokumenteerida.
  • Brandoni Sfinksi õpetus - ulatuslik juhend Sphinxi kasutamise kohta

Machiels, Brecht. “Rinohtype: Pythoni dokumentide töötleja - Rinohtype 0.3.1.Dev0 dokumentatsioon.” Rinohtype.readthedocs.io. N.p., 2016. Veeb. 17. juuni 2018.

Sphinx-doc.org. (2018). Ülevaade - Sphinx 1.8.0+ dokumentatsioon. [võrgus] saadaval aadressil: http://www.sphinx-doc.org/en/master/ [Juurdepääs 17. juuni 2018].