Egy egyszerű bemutató a Python-projekt dokumentálásához Sphinx és Rinohtype használatával

A kódok dokumentálása az egyik olyan feladat, amelyet igazán nem akarok elvégezni, de azért mindegyikért megteszem.

Valószínűleg ezt fogja hallani tőlem, amikor első éves informatikai hallgató voltam. Úgy találtam, hogy a kódoló dokumentum unalmas és haszontalan, mivel már tudom, hogy mit tesz a kódom, és az egyetlen személy, aki valószínűleg elolvassa, a professzor, aki ellenőrzi.

Csak egy napig nem értettem annak jelentőségét, meg kellett vizsgálnom azt a nem dokumentált kódot, amelyet referenciaként írtam évekkel ezelőtt, és ahelyett, hogy átfutottam volna rajta, sok időt töltöttem nagyon zavartan azzal, hogy felépítettem a projektet, sőt hogyan kell futtatni.

Manapság sok eszköz áll rendelkezésre, amelyek segítenek a kód dokumentálásában. Nemrég tanultam olyan eszközökről, amelyek megkönnyítik az intelligens és gyönyörű dokumentáció elkészítését. Ezek közül kettő a Szfinx és a Rinohtype.

A Sphinx, amelyet Georg Brandl írt és a BSD licenc alapján engedélyezett, eredetileg a Python dokumentációhoz hozták létre, és kiváló lehetőségeket kínál a szoftverprojektek dokumentálására számos nyelven (Sphinx-doc.org, 2018).

A Rinohtype és a Sphinx párosítva modern alternatívát kínál a LaTeX-hez. Ez egy Sphinx háttérrendszert biztosít, amely lehetővé teszi professzionális típusú PDF-dokumentumok (Machiels) előállítását.

Ebben az oktatóanyagban az Sphinx és Rinohtype segítségével HTML és PDF dokumentációs fájlokat készítek egy egyszerű API projekthez, amelyet én írtam, amely kezeli a Tanári rekordok listáját (Github Project Link).

  1. Klónozzuk a projektet, és töröljük / mozgatjuk a docs mappát, hogy követhessen engem az új dokumentáció létrehozásakor.
  2. Lépjen a projekt gyökérkönyvtárába.
  3. Hozzon létre és aktiválja a Python 3 virtuális környezetet
virtualenv -p python3 
forrás  / bin / aktiválás
Itt a „virtuális” környezetet neveztem el

4. Telepítse az összes projektkövetelményt

pip install -r követelmények.txt

Megjegyzés: Az Sphinx és a Rinohtype már benne vannak a követelmények.txt fájlban. Ha telepíteni szeretné őket a projekt virtuális környezetében, akkor dolgozik az alábbi parancsokon.

pip install Sphinx
pip install rinohtype

5. Hozzon létre egy docs könyvtárat és a CD-t ebbe a könyvtárba.

mkdir docs
CD-dokumentumok

6. A Sfinx beállítása

szfinxszerű gyorstalpaló
Kövesse most ezt a konfigurációt. Ezt később saját maga konfigurálhatja.az előző kép folytatása

7. Nyílt forráskódú / konf.py

  • Konfigurálja a gyökérkönyvtár elérési útját
Kommentetlen sorok 15–17Módosítsa az elérési utat '../ ..' -re, és adja hozzá a sys.setrecursionlimit (1500)

Az elérési útnak a projekt gyökérkönyvtárára kell mutatnia, és a projekt struktúrájára nézve a conf.py-től a gyökér eléréséhez két szülő könyvtárat kell elérnünk.

A projekt felépítése
  • Adja hozzá a Rinohtype fájlt a kiterjesztés listájához
'Rinoh.frontend.sphinx'
  • Távolítsa el a latex elemeket
tegye ezt megA formátumot tovább módosíthatja, ezek csak az alapértelmezés.

8. Nyissa meg az index.rst elemet, és változtassa meg a tartalmat a következőre. (A teljes tartalomhoz kattintson az index.rst linkre)

A kódex dokumentációja
**************************
.. toctree ::
   : maximális mélység: 2
   : felirat: Tartalom:

TeacherAPI fő
===================
.. automodule :: kb
   : Tag:

TeacherAPI vezérlő
=====================
.. automodule :: teacherAPI.kontroller
   : Tag:

TeacherAPI modellek
=================
.. automodule :: teacherAPI.models
   : Tag:

TeacherAPI adatbázis
===================
.. automodule :: teacherAPI.database
   : Tag:

TeacherAPI lakott
===================
.. automodule :: teacherAPI.populate
   : Tag:

9. Hozza létre a HTML és PDF dokumentációs fájlokat.

  • Még mindig a docs könyvtárban fut
hogy html
sphinx-build -b rinoh source _build / rinoh

MEGJEGYZÉS SZERKESZTÉS [2019. március 16]: A pdf fájl létrehozása nem sikerül, ha a Python verziója ≥3.7.0 (Github kiadási hivatkozás)

Az első sor a HTML fájlt a docs / build / html / index.html könyvtárban hozza létre

Az index.html nézeteAz index.html nézete

A második sor a PDF fájlt a docs / _build / rinoh / SimpleTeacherDataAPI.pdf fájlban hozza létre.

A dokumentáció címlapjaTartalomjegyzékA dokumentáció mintaoldala

Miután tapasztalatokat szereztem a csapatprojektekben, elkezdtem felértékelni a kód dokumentálását, és bár nem mondanám, hogy ez a leginkább élvezetes feladat, ez egyértelműen megbízható, és azt a programozóknak kell gyakorolniuk.

További információ a Sfinxről:

  • Áttekintés - Sphinx 1.8.0+ dokumentáció

Egyéb hasznos oktatóanyagok:

  • Projekt dokumentálása a Sphinx segítségével - Ez segített megérteni, hogyan kell dokumentálni a kódomat Python dokumentumok segítségével.
  • Brandon Sphinx bemutatója - Átfogó bemutató a Sphinx használatához

Machiels, Brecht. “Rinohtype: A Python dokumentumfeldolgozó - Rinohtype 0.3.1.Dev0 Documentation.” Rinohtype.readthedocs.io. N.p., 2016. Web. 2018. június 17.

Sphinx-doc.org. (2018). Áttekintés - Sphinx 1.8.0+ dokumentáció. [online] Elérhető a következő címen: http://www.sphinx-doc.org/en/master/ [Hozzáférés 2018. június 17-én].