Hozza ki a legtöbbet projektje dokumentumaiból – használja a Sphinxet vonzó, átfogó HTML-dokumentáció létrehozásához.

A Sphinx a dokumentációkészítés egyik legnépszerűbb eszköze. A Python közösségben a fejlesztők ezt az ingyenes és nyílt forráskódú szoftvert használják. Közvetlenül a kód- vagy leértékelési fájlokból képes kivonatolni a szöveget, majd különféle formátumú dokumentumok létrehozására használhatja, például egyszerű szöveg, HTML, PDF és EPUB.

A Szfinx beállítása

A Sphinx beállítása előtt vessen egy pillantást annak működésére és néhány fő funkciójára.

Mi az a szfinx és mit csinál?

Mint említettük, a Sphinx egy dokumentációs generátor. Alapértelmezés szerint a reStructuredText (RST) jelölőnyelvet használja, de harmadik féltől származó bővítményeken keresztül is használja a Markdownt, a népszerű egyszerű szöveges jelölőnyelvet. Ezután ezeket az RST- vagy leértékelési fájlokat HTML-vé, PDF-vé, kézikönyvoldalakká vagy más kívánt formátumba konvertálja.

A Sphinx néhány jellemzője:

  • Képes dokumentációt generálni kódból.
    • instagram viewer
  • Lehetőség a különböző dokumentumoldalakra történő kereszthivatkozásra függvények, osztályok, hivatkozások és szószedeti kifejezések automatikus hivatkozásaival.
  • Szintaxis kiemelés kódblokkokhoz.
  • Olyan témák támogatása, amelyek megváltoztathatják a dokumentumok megjelenését és hangulatát.
  • A dokumentumfa egyszerű meghatározása a tartalomjegyzéken keresztül.
  • Képes integrálni harmadik féltől származó bővítményekkel, hogy további funkciókat adjon a dokumentumokhoz, például tesztelje a kódrészleteket.

A Sphinx telepítése

A Sphinx telepítése előtt győződjön meg arról, hogy rendelkezik A Python 3 telepítve van a fejlesztői környezetben. Ezután a pip csomagkezelővel telepítheti a Sphinxet a következő parancs futtatásával a terminálon:

pip install szfinx

Ezzel letölti és telepíti a Sphinxet és függőségeit.

A telepítés után futtassa a következőt a parancssorban.

szfinx-build --verzió

Ha minden jól működött, látnia kell az imént telepített Sphinx csomag verziószámát.

Új Szfinx projekt létrehozása

A Sphinx telepítése után keresse meg a munkakönyvtárat, és futtassa a sphinx-quickstart parancsot egy új Sphinx projekt létrehozásához.

szfinx-gyorsindítás

Ez a parancs arra kéri Önt, hogy válaszoljon egy sor kérdésre a Sphinx projekt konfigurálásával kapcsolatban. Megadhatja a projekt nevét, és a többi kérdéshez az alapértelmezett beállításokat használhatja. A jövőben érdemes lehet a projektje alapján testreszabni a válaszokat.

Ha felsorolja a könyvtár tartalmát, látni fogja, hogy ez a parancs létrehoz néhány fájlt az Ön számára. A conf.py tartalmazza a konfigurációs értékeket, az index.rst pedig a dokumentáció üdvözlő oldalaként szolgál. A build könyvtár fogja tárolni a generált dokumentációt, és a Sphinx egy Makefile-t (Windows rendszeren make.bat) használ a dokumentáció összeállításához.

Dokumentáció írása Szfinx segítségével

A könyvtár gyökérében található index.rst fájl az alkalmazás kezdőlapja. Tehát nyissa meg egy szövegszerkesztővel, mint a VS Code – vagy bármilyen más jó, ingyenes kódszerkesztő- szerkeszteni.

Módosíthatja az index.rst fájlt, ahogy jónak látja, de egy dolog, aminek legalább rendelkeznie kell, a gyökér toctree (tartalomjegyzék fa) direktívája. Ez elengedhetetlen, mivel több fájlt egyetlen dokumentumhierarchiához köt össze.

Ha dokumentációt szeretne hozzáadni az index.rst fájlhoz, használhatja az RST jelölést.

Példaként vegyünk egy index.rst fájlt a math_utils modulhoz. Ez a fájl tartalmazhat egy rövid áttekintést a modul céljáról és egy tartalomjegyzéket, amely a dokumentáció más oldalaira hivatkozik.

Üdvözli a Math Utils
.. tokfa::
 :maxmélység: 2


Elkezdeni


A modul használatához a következőkre lesz szüksége:


* Python telepítve.


* Szövegszerkesztő


Math Utils


A "math-utils" modul olyan alapvető matematikai funkciókat biztosít, mint az összeadás és
kivonás.

Igény szerint további .rst fájlokat is hozzáadhat. Például létrehozhat egy hozzájárulási útmutatót egy contributing.rst nevű fájlban, amely a következő hozzájárulási irányelveket tartalmazza.

Hozzájárulási útmutató
Szívesen fogadjuk projektünkhöz való hozzájárulásukat! Íme néhány iránymutatás
közreműködő:


- Forgassa a projektet a GitHubon.
- Végezze el a módosításokat egy új ágon.
- Írjon teszteket annak biztosítására, hogy a változtatások megfelelően működjenek.
- Nyújtson le lehívási kérelmet a módosításokkal.
- Végezze el a kívánt módosításokat.
Köszönjük a közreműködést!

Ezután linkelheti ezt a fájlt az index.rst webhelyről úgy, hogy új szakaszt ad hozzá a toctree direktívához:

.. tokfa::
 :maxmélység: 2
 :caption: Tartalomjegyzék

 hozzájárulva

Ezzel a tartalomjegyzékben egy új elem jön létre közreműködés néven, amelyre kattintva a felhasználó a hozzájárulási oldalra kerül.

Miután megírta a dokumentációt, a következő lépés az elkészítése. Itt a dokumentáció összeállítása HTML, kézikönyv vagy PDF oldalak generálását jelenti az RST-fájlokból.

A dokumentáció készítése

A dokumentáció Sphinx használatával történő összeállításához futtassa a make html parancsot annak a mappának a gyökerében, ahol a makefile található.

csinálj html-t

Látnia kell a HTML-fájlokat a build mappában. Ha hibák történtek a felépítés során, a Sphinx értesíti Önt a terminálban.

A dokumentáció megtekintéséhez nyissa meg az index.html fájlt a böngészőben:

A tartalomjegyzékből el kell tudni navigálni a közreműködő útmutatóhoz.

A dokumentáció testreszabása

Jelenleg a dokumentációnak van néhány alapvető stílusa. Ha testre szeretné szabni, esetleg a márkaszínek hozzáadásával, vagy akár egy sötét mód hozzáadásával, telepíthet és használhat más beépített témák vagy létrehozhat saját egyéni témát.

A demonstrációhoz próbálja megváltoztatni a témát a természetnek nevezettre:

  1. Nyissa meg a Conf.py Sphinx konfigurációs fájlt a Sphinx projekt könyvtárában.
  2. Keresse meg azt a sort, amely meghatározza a html_theme beállítást, és módosítsa természetre
  3. Mentse el a konfigurációs fájlt, és építse újra a dokumentációt a módosítások megtekintéséhez.

Így kell kinéznie a dokumentáció kezdőlapjának.

Ha nem szeretné használni a beépített témákat, mindig használhatja a harmadik féltől származó Szfinx téma helyette.

A kód dokumentálása Docsstringek segítségével

A Sphinx az RST-fájlokba írt szövegből állítja elő a Python-dokumentációt. Bár ez bizonyos esetekben elegendő, érdemes lehet a kódjában lévő docstringeket is használni a modul szintjén.

A docstringek közvetlenül a projekt forrásfájljaiban találhatók. Lehetővé teszik, hogy leírja a kód működését, példákat kínáljon, és még teszteket is készítsen ezekhez a példákhoz. Miután megírta a docstringeket, a Sphinx segítségével dokumentációt hozhat létre belőlük.