Vienkārša apmācība par to, kā dokumentēt Python projektu, izmantojot Sfinksu un Rinohtype

Kodu dokumentēšana ir viens no uzdevumiem, kuru es patiešām nevēlos darīt, taču vienalga to darīšu atbilstoši atzīmēm.

Droši vien to dzirdēsit no manis, kad biju pirmā kursa datorzinātņu students. Manuprāt, dokumentēšanas kods ir garlaicīgs un bezjēdzīgs, jo es jau zinu, ko dara mans kods, un vienīgais, kurš, iespējams, to lasīs, ir profesors, kurš to pārbauda.

Es nesapratu tā nozīmi tikai vienu dienu, man vajadzēja aplūkot to dokumentēto kodu, kuru es uzrakstīju pirms gadiem atsauces nolūkos, un tā vietā, lai tikai to caurskatītu, es daudz laika pavadīju diezgan apjukuši par to, kā es strukturēju projektu un pat kā to vadīt.

Mūsdienās ir pieejams ļoti daudz rīku, kas mums palīdz koda dokumentēšanā. Nesen es uzzināju par rīkiem, kas ļauj viegli izveidot inteliģentu un skaistu dokumentāciju. Divas no tām ir Sfinksa un Rinohtype.

Sfinksa, kuru rakstījis Georgs Brendls un licencēts saskaņā ar BSD licenci, sākotnēji tika izveidots Python dokumentācijai, un tam ir lieliskas iespējas programmatūras projektu dokumentēšanai dažādās valodās (Sphinx-doc.org, 2018).

Rinohtype, pārī ar Sphinx, piedāvā modernu alternatīvu LaTeX. Tas nodrošina Sphinx aizmugures programmu, kas ļauj profesionāli ģenerēt PDF dokumentus (Machiels).

Šajā apmācībā es izmantošu Sphinx un Rinohtype HTML un PDF dokumentācijas failu izveidošanai attiecīgi vienkāršam API projektam, kuru es uzrakstīju un kurš pārvalda Skolotāju ierakstu sarakstu (Github Project Link).

  1. Klonējiet projektu un izdzēsiet / pārvietojiet dokumentu mapi, lai jūs varētu sekot man, veidojot jauno dokumentāciju.
  2. Dodieties uz projekta saknes direktoriju.
  3. Izveidojiet un aktivizējiet Python 3 virtuālo vidi
virtualenv -p python3 
avots  / bin / aktivizēt
Šeit es savu virtuālo vidi nosaucu par “venv”

4. Instalējiet visas projekta prasības

pip instalēt -r prasības.txt

Piezīme: Sfinksa un Rinohtype jau ir failu.txt failā. Ja vēlaties tos instalēt projekta virtuālajā vidē, pie kura strādājat, izmantojiet tālāk norādītās komandas.

pip instalēt Sfinksu
pip instalēt rinohtype

5. Izveidojiet dokumentu direktoriju un cd šajā direktorijā.

mkdir docs
CD dokumenti

6. Iestatīt Sfinksu

sfinksa-ātrā starta
Pagaidām izpildiet šo konfigurāciju. To vēlāk var pārkonfigurēt pats.iepriekšējā attēla turpinājums

7. Atvērtā koda / konf.py

  • Konfigurējiet ceļu uz saknes direktoriju
Nekomentēšanas līnijas 15. – 17Mainiet ceļu uz “../ ..” un pievienojiet sys.setrecursionlimit (1500)

Ceļam vajadzētu norādīt uz projekta saknes direktoriju un aplūkojot projekta struktūru, no conf.py mums vajadzētu sasniegt sakni, paceļot divus vecākkatalogus.

Projekta struktūra
  • Papildu sarakstam pievienojiet Rinohtype
'rinoh.frontend.sphinx'
  • Nekomentējiet lateksa elementus
nekomentē šosJūs varat mainīt formātu tālāk, tie ir tikai noklusējuma iestatījumi.

8. Atveriet index.rst un mainiet saturu uz sekojošo. (Lai iegūtu pilnu saturu, noklikšķiniet uz saites index.rst.)

Kodeksa dokumentācija
*******************,5
.. toctree ::
   : maksimālais dziļums: 2
   : paraksts: Saturs:

TeacherAPI galvenā
===================
.. automobilis :: app
   :dalībnieki:

SkolotājuAPI kontrolieris
=====================
.. automašīna :: skolotājsAPI.kontrollers
   :dalībnieki:

SkolotājuAPI modeļi
=================
.. automašīna :: skolotājsAPI.modeļi
   :dalībnieki:

SkolotājuAPI datu bāze
===================
.. automašīna :: skolotājsAPI.database
   :dalībnieki:

Apdzīvo skolotājuAPI
===================
.. automašīna :: skolotājsAPI.populācija
   :dalībnieki:

9. Izveidojiet HTML un PDF dokumentācijas failus.

  • Joprojām darbojas dokumentu direktorijā
padarīt html
sfinksa būvēt-b rinoh avots _build / rinoh

PIEZĪME Rediģēt [2019. gada 16. marts]: pdf faila izveidošana neizdosies, ja Python versija ir ≥3.7.0 (atsauce uz Github izdošanu).

Pirmajā rindā HTML fails tiks izveidots failā docs / build / html / index.html

Skatījums index.htmlSkatījums index.html

Otrajā rindā tiks izveidots PDF fails docs / _build / rinoh / SimpleTeacherDataAPI.pdf

Dokumentācijas titullapāSatura rādītājsDokumentācijas lapas paraugs

Pēc tam, kad esmu pieredzējis komandas projektos, es sāku novērtēt koda dokumentēšanu un, lai arī es neteiktu, ka tas ir vispatīkamākais uzdevums, tas noteikti ir uzticams, un to vajadzētu praktizēt programmētājiem .

Lai uzzinātu vairāk par Sfinksu:

  • Pārskats - Sphinx 1.8.0+ dokumentācija

Citas noderīgas konsultācijas:

  • Projekta dokumentēšana, izmantojot Sfinksu - tas man palīdzēja saprast, kā dokumentēt manu kodu, izmantojot Python doktrīnas.
  • Brendona Sfinksa apmācība - plaša apmācība par Sfinksa lietošanu

Machiels, Brecht. “Rinohtype: Python Document Processor - Rinohtype 0.3.1.Dev0 Documentation.” Rinohtype.readthedocs.io. N.p., 2016. Web. 2018. gada 17. jūnijs.

Sfinksa-doc.org. (2018). Pārskats - Sphinx 1.8.0+ dokumentācija. [tiešsaiste] Pieejams vietnē: http://www.sphinx-doc.org/en/master/ [Piekļuve 2018. gada 17. jūnijam].