Preprosta vadnica o tem, kako dokumentirati svoj Python Project s pomočjo Sphinx in Rinohtype

Dokumentiranje kode je ena od nalog, ki je res ne želim opravljati, vseeno pa jo bom naredil za ocene.

To boste verjetno slišali od mene, ko sem bil študent prvega letnika računalništva. Dokumentiranje kode se mi zdi dolgočasno in neuporabno, saj že vem, kaj počne moja koda, in edina oseba, ki jo bo verjetno prebral, je profesor, ki jo preverja.

Dokler nekega dne nisem razumel njegove pomembnosti, sem moral za referenco pogledati to nedokumentirano kodo, ki sem jo napisal pred leti, in namesto da bi jo preprosto prelistaval, sem porabil veliko časa, da sem bil zelo zmeden, kako sem strukturiral projekt in celo kako ga voditi.

Danes je na voljo veliko orodij, ki nam pomagajo pri dokumentiranju kode. Pred kratkim sem izvedel orodja, ki olajšajo izdelavo inteligentne in lepe dokumentacije. Dva od teh sta Sfinga in Rinohtype.

Sphinx, ki ga je napisal Georg Brandl in je licenciran pod licenco BSD, je bil prvotno ustvarjen za dokumentacijo Python in ima odlične zmogljivosti za dokumentacijo programov programske opreme v različnih jezikih (Sphinx-doc.org, 2018).

Rinohtype, povezan s Sphinxom, ponuja sodobno alternativo LaTeX-u. Ponuja nadomestni računalnik Sphinx, ki omogoča ustvarjanje profesionalnih vrst PDF dokumentov (Machiels).

V tej vadnici bom Sphinx in Rinohtype uporabil za izdelavo datotek z dokumentacijo HTML in PDF v preprostem projektu API, ki sem ga napisal in upravlja seznam učiteljskih zapisov (Github Project Link).

  1. Klonirajte projekt in izbrišite / premaknite mapo z dokumenti, da mi boste lahko sledili pri ustvarjanju nove dokumentacije.
  2. Pojdite v korenski imenik projekta.
  3. Ustvarite in aktivirajte navidezno okolje Python 3
virtualenv -p python3 
vir  / bin / activate
Tu sem svoje virtualno okolje poimenoval 'venv'

4. Namestite vse zahteve projekta

pip namestite -r zahteve.txt

Opomba: Sfinga in Rinohtype sta že znotraj datoteke datoteke.txt. Če jih želite namestiti v virtualno okolje projekta, na katerem delate, uporabite spodnje ukaze.

pip namestite Sphinx
pip namestite rinohtype

5. Ustvarite imenik dokumentov in ga vnesite v ta imenik.

mkdir dok
CD dokumenti

6. Nastavite Sfingo

sfing-hitri zagon
Zaenkrat sledite tej konfiguraciji. To lahko pozneje prilagodite sami.nadaljevanje prejšnje slike

7. Open source / conf.py

  • Konfigurirajte pot do korenskega imenika
Vrstice brez komentarjev 15–17Spremenite pot v »../ ..« in dodajte sys.setrecursionlimit (1500)

Pot naj kaže na korenski imenik projekta in pogled na strukturo projekta, od conf.py pa bi morali doseči koren, tako da gremo po dva nadrejena imenika.

Struktura projekta
  • Na seznam končnic dodajte Rinohtype
'rinoh.frontend.sphinx'
  • Odklopite elemente iz lateksa
komentirajte teObliko lahko še spremenite, to so samo privzeto.

8. Odprite index.rst in vsebino spremenite v naslednjo. (Za celotno vsebino kliknite povezavo index.rst)

Dokumentacija za Kodeks
**************************
.. toctree ::
   : maxdepth: 2
   : napis: Vsebina:

UčiteljAPI glavni
===================
.. automodule :: app
   : člani:

UčiteljAPI kontroler
======================
.. avtododul :: učiteljAPI.kontroler
   : člani:

Modeli TeacherAPI
=================
.. avtododul :: učiteljAPI.models
   : člani:

Učiteljska baza podatkov
===================
.. avtododul :: učiteljica.I.podatkovna baza podatkov
   : člani:

UčiteljAPI populi
===================
.. avtododul :: učiteljAPI.populate
   : člani:

9. Ustvarite dokumentacijsko datoteko HTML in PDF.

  • Še vedno teče v imeniku dokumentov
naredite html
sphinx-build -b rinoh vir _build / rinoh

UREDITE OPOMBO [16. marec 2019]: Če bo vaša različica Pythona ≥3.7.0 (referenca izdaje Github), izgradnja pdf datoteke ne bo uspela

Prva vrstica bi ustvarila datoteko HTML v docs / build / html / index.html

Pogled na index.htmlPogled na index.html

Druga vrstica bi ustvarila datoteko PDF v docs / _build / rinoh / SimpleTeacherDataAPI.pdf

Naslovna stran dokumentacijeKazalo vsebineVzorčna stran dokumentacije

Po izkušnjah v timskih projektih sem začel razvijati spoštovanje pri dokumentiranju kode in čeprav, ne bi rekel, da je to najbolj uživaška naloga, je vsekakor zanesljiv in bi ga morali izvajati programerji .

Če želite izvedeti več o Sfingi:

  • Pregled - dokumentacija Sphinx 1.8.0+

Druge uporabne vadnice:

  • Dokumentiranje projekta s pomočjo Sphinxa - To mi je pomagalo pri razumevanju, kako dokumentirati svojo kodo s pomočjo dokumentov Python.
  • Brandon's Sphinx Tutorial - Obširna vadnica o uporabi Sphinxa

Machiels, Brecht. "Rinohtype: Procesor za dokumentacijo Python - Rinohtype 0.3.1.Dev0 Documentation." Rinohtype.readthedocs.io. N.p., 2016. Splet. 17. junij 2018.

Sphinx-doc.org. (2018). Pregled - dokumentacija Sphinx 1.8.0+. [na spletu] Dostopno na: http://www.sphinx-doc.org/sl/master/ [Dostopno 17. junija 2018].