Maksimalno iskoristite dokumente svog projekta—koristite Sphinx za generiranje atraktivne, sveobuhvatne HTML dokumentacije.

Sphinx je jedan od najpopularnijih alata za generiranje dokumentacije. U cijeloj zajednici Pythona programeri koriste ovaj besplatni softver otvorenog koda. Može izdvojiti tekst izravno iz vašeg koda ili markdown datoteka i zatim ga koristiti za generiranje dokumentacije u različitim formatima kao što su obični tekst, HTML, PDF i EPUB.

Postavljanje Sfinge

Prije nego što postavite Sphinx, pogledajte što radi i neke od njegovih glavnih značajki.

Što je Sphinx i čemu služi?

Kao što je spomenuto, Sphinx je generator dokumentacije. Prema zadanim postavkama koristi označni jezik reStructuredText (RST), ali putem proširenja trećih strana također može koristite Markdown, popularni jezik za označavanje običnog teksta. Zatim pretvara te RST ili datoteke markdowna u HTML, PDF, stranice priručnika ili druge formate koje preferirate.

Neke od značajki koje uključuje Sphinx su:

  • Sposobnost generiranja dokumentacije iz koda.
    • instagram viewer
  • Sposobnost unakrsnog upućivanja na različite stranice dokumenata pomoću automatskih poveznica za funkcije, klase, citate i termine iz pojmovnika.
  • Označavanje sintakse za blokove koda.
  • Podrška za teme koje mogu promijeniti izgled i dojam dokumenata.
  • Jednostavna definicija stabla dokumenata putem tablice sadržaja.
  • Mogućnost integracije s ekstenzijama trećih strana za dodavanje više funkcionalnosti dokumentima kao što je testiranje isječaka koda.

Instalacija Sphinxa

Prije instaliranja Sphinxa, provjerite jeste li Python 3 instaliran u vašem razvojnom okruženju. Zatim možete upotrijebiti pip upravitelj paketa za instaliranje Sphinxa pokretanjem sljedeće naredbe na vašem terminalu:

pip instalirati sfingu

Ovo će preuzeti i instalirati Sphinx i njegove ovisnosti.

Nakon instalacije pokrenite sljedeće na naredbenom retku.

sphinx-build --verzija

Ako je sve dobro radilo, trebali biste vidjeti broj verzije Sphinx paketa koji ste upravo instalirali.

Stvaranje novog projekta Sphinx

Nakon što ste instalirali Sphinx, dođite do vašeg radnog direktorija i pokrenite naredbu sphinx-quickstart za stvaranje novog Sphinx projekta.

sfinga-brzi početak

Ova naredba će od vas tražiti da odgovorite na niz pitanja o tome kako konfigurirati vaš Sphinx projekt. Možete navesti naziv projekta i koristiti zadane opcije za ostala pitanja. U budućnosti biste mogli prilagoditi odgovore na temelju svog projekta.

Ako ispišete sadržaj svog imenika, vidjet ćete da ova naredba stvara neke datoteke za vas. Conf.py sadrži konfiguracijske vrijednosti, a index.rst služi kao početna stranica vaše dokumentacije. Direktorij za izradu će ugostiti generiranu dokumentaciju, a Sphinx koristi Makefile (make.bat na Windowsima) za izradu dokumentacije.

Pisanje dokumentacije pomoću Sphinxa

Datoteka index.rst u korijenu vašeg imenika početna je stranica vaše aplikacije. Dakle, otvorite ga uređivačem teksta kao što je VS Code—ili bilo koji drugi dobar, besplatni uređivač koda— da ga uredite.

Možete promijeniti index.rst kako vam odgovara, ali jedna stvar koju bi barem trebao imati je root toctree (stablo tablice sadržaja) direktiva. To je bitno jer povezuje više datoteka u jednu hijerarhiju dokumenata.

Da biste dodali dokumentaciju u datoteku index.rst, možete koristiti RST markup.

Kao primjer, razmotrite datoteku index.rst za modul math_utils. Ova datoteka može sadržavati kratki pregled svrhe modula i tablicu sadržaja koja povezuje na druge stranice dokumentacije.

Dobro došli u Math Utils
.. toctree::
 :maxdepth: 2


Početak rada


Za korištenje ovog modula trebat će vam sljedeće:


* Python instaliran.


* Uređivač teksta


Math Utils


Modul `math-utils` pruža osnovne matematičke funkcije poput zbrajanja i
oduzimanje.

Po potrebi možete dodati još .rst datoteka. Na primjer, možete stvoriti vodič za doprinos u datoteci pod nazivom contributing.rst koja sadrži sljedeće smjernice za doprinos.

Vodič za doprinos
Pozdravljamo doprinose našem projektu! Evo nekoliko smjernica za
pridonosi:


- Račvajte projekt na GitHubu.
- Napravite svoje promjene na novoj grani.
- Napišite testove kako biste osigurali da vaše promjene rade ispravno.
- Pošaljite zahtjev za povlačenje sa svojim promjenama.
- Napravite sve tražene promjene.
Hvala vam na doprinosu!

Zatim možete povezati ovu datoteku iz index.rst dodavanjem novog odjeljka toctree direktivi:

.. toctree::
 :maxdepth: 2
 :caption: Sadržaj

 pridonoseći

Ovo stvara novu stavku pod nazivom doprinos u tablici sadržaja koja vodi korisnika na stranicu doprinosa kada se klikne.

Nakon što ste napisali dokumentaciju, sljedeći korak je njena izrada. Ovdje izrada dokumentacije znači generiranje HTML stranica, priručnika ili PDF stranica iz RST datoteka.

Izrada dokumentacije

Za izradu dokumentacije koristeći Sphinx, morat ćete pokrenuti make html naredbu u korijenu vaše mape gdje se nalazi makefile.

napraviti html

Trebali biste vidjeti HTML datoteke u mapi za izradu. Ako je bilo grešaka tijekom izgradnje, Sphinx će vas obavijestiti u terminalu.

Za pregled dokumentacije otvorite datoteku index.html u svom pregledniku:

Trebali biste moći doći do vodiča za doprinos iz tablice sadržaja.

Prilagodba dokumentacije

Upravo sada, dokumentacija ima neki osnovni stil. Ako ga želite prilagoditi, možda dodavanjem boja svoje marke ili čak dodavanjem tamnog načina rada, možete instalirati i koristiti druge ugrađene teme ili izradite vlastitu prilagođenu temu.

Za demonstraciju pokušajte promijeniti temu u onu koja se zove priroda:

  1. Otvorite Sphinx konfiguracijsku datoteku conf.py u vašem direktoriju Sphinx projekta.
  2. Potražite liniju koja definira opciju html_theme i promijenite je u prirodu
  3. Spremite konfiguracijsku datoteku i ponovno izradite dokumentaciju da biste vidjeli svoje promjene.

Ovako bi trebala izgledati početna stranica dokumentacije.

Ako ne želite koristiti ugrađene teme, uvijek možete koristiti a tema Sphinx treće strane umjesto toga.

Dokumentiranje vašeg koda pomoću nizova dokumenata

Sphinx generira vašu Python dokumentaciju iz teksta koji napišete u RST datotekama. Iako je to u nekim slučajevima dovoljno, možda ćete također htjeti koristiti nizove dokumenata u svom kodu za to na razini modula.

Nizovi dokumenata žive izravno unutar izvornih datoteka vašeg projekta. Omogućuju vam da opišete što kod radi, pružite primjere, pa čak i napravite testove za te primjere. Nakon što ste napisali nizove dokumenata, možete generirati dokumentaciju iz njih koristeći Sphinx.