Profitați la maximum de documentele proiectului dvs. - utilizați Sphinx pentru a genera documentație HTML atractivă și cuprinzătoare.

Sphinx este unul dintre cele mai populare instrumente pentru generarea documentației. În comunitatea Python, dezvoltatorii folosesc acest software gratuit și open-source. Poate extrage text direct din fișierele de cod sau markdown și apoi îl poate utiliza pentru a genera documentație în diferite formate, cum ar fi text simplu, HTML, PDF și EPUB.

Configurarea Sfinxului

Înainte de a configura Sphinx, aruncați o privire la ceea ce face și câteva dintre caracteristicile sale principale.

Ce este Sfinxul și ce face?

După cum am menționat, Sphinx este un generator de documentație. În mod implicit, folosește limbajul de marcare reStructuredText (RST), dar prin extensii terțe, poate, de asemenea utilizați Markdown, popularul limbaj de marcare pentru text simplu. Apoi convertește aceste fișiere RST sau markdown în HTML, PDF, pagini de manual sau în alte formate pe care le preferați.

instagram viewer

Unele dintre caracteristicile pe care le include Sphinx sunt:

  • Abilitatea de a genera documentație din cod.
  • Abilitatea de a face referințe încrucișate diferitelor pagini de document folosind link-uri automate pentru funcții, clase, citări și termeni de glosar.
  • Evidențierea sintaxelor pentru blocurile de cod.
  • Suport pentru teme care pot schimba aspectul documentelor.
  • Definirea simplă a arborelui documentelor printr-un cuprins.
  • Posibilitatea de a se integra cu extensii terțe pentru a adăuga mai multe funcționalități documentelor, cum ar fi testarea fragmentelor de cod.

Instalarea Sfinxului

Înainte de a instala Sphinx, asigurați-vă că aveți Python 3 instalat în mediul dumneavoastră de dezvoltare. Puteți utiliza apoi managerul de pachete pip pentru a instala Sphinx rulând următoarea comandă în terminalul dvs.:

pip install sfinx

Acest lucru va descărca și instala Sphinx și dependențele sale.

După instalare, executați următoarele în linia de comandă.

sfinx-build --versiune

Dacă totul a funcționat bine, ar trebui să vedeți numărul versiunii pentru pachetul Sphinx pe care tocmai l-ați instalat.

Crearea unui nou proiect Sfinx

După ce ați instalat Sphinx, navigați la directorul de lucru și rulați comanda sphinx-quickstart pentru a crea un nou proiect Sphinx.

sfinx-pornire rapidă

Această comandă vă va cere să răspundeți la o serie de întrebări despre cum să vă configurați proiectul Sphinx. Puteți specifica numele proiectului și puteți utiliza opțiunile implicite pentru celelalte întrebări. În viitor, poate doriți să personalizați răspunsurile în funcție de proiectul dvs.

Dacă enumerați conținutul directorului dvs., veți vedea că această comandă creează câteva fișiere pentru dvs. Conf.py conține valorile de configurare, iar index.rst servește ca pagină de întâmpinare a documentației dumneavoastră. Directorul de compilare va găzdui documentația generată, iar Sphinx utilizează un Makefile (make.bat pe Windows) pentru a construi documentația.

Scrierea documentației folosind Sphinx

Fișierul index.rst din rădăcina directorului dvs. este pagina de pornire a aplicației dvs. Deci, deschideți-l cu un editor de text precum VS Code—sau orice alt editor de cod bun, gratuit- pentru a-l edita.

Puteți schimba index.rst după cum credeți de cuviință, dar un lucru pe care ar trebui să-l aibă cel puțin este directiva rădăcină toctree (arborele de cuprins). Acest lucru este esențial deoarece conectează mai multe fișiere la o singură ierarhie de documente.

Pentru a adăuga documentație la fișierul index.rst, puteți utiliza marcajul RST.

Ca exemplu, luați în considerare un fișier index.rst pentru modulul math_utils. Acest fișier poate include o scurtă prezentare generală a scopului modulului și un cuprins care trimite către alte pagini ale documentației.

Bun venit la Math Utils
.. toctree::
 :maxdepth: 2


Noțiuni de bază


Pentru a utiliza acest modul, veți avea nevoie de următoarele:


* Python instalat.


* Un editor de text


Utilaje matematice


Modulul `math-utils` oferă funcții matematice de bază precum adunarea și
scădere.

Puteți adăuga mai multe fișiere .rst după cum este necesar. De exemplu, puteți crea un ghid de contribuție într-un fișier numit contributing.rst care conține următoarele reguli de contribuție.

Ghid de contribuție
Salutăm contribuțiile la proiectul nostru! Iată câteva îndrumări pentru
contribuind:


- Bifurcați proiectul pe GitHub.
- Faceți modificările pe o nouă filială.
- Scrieți teste pentru a vă asigura că modificările funcționează corect.
- Trimiteți o cerere de extragere cu modificările dvs.
- Faceți orice modificări solicitate.
Vă mulțumim pentru contribuție!

Apoi puteți lega acest fișier de la index.rst adăugând o nouă secțiune la directiva toctree:

.. toctree::
 :maxdepth: 2
 :caption: Cuprins

 contribuind

Acest lucru creează un nou articol numit contribuție în cuprinsul care duce utilizatorul la pagina de contribuții atunci când este făcut clic.

Odată ce ați scris documentația, următorul pas este să o construiți. Aici, construirea documentației înseamnă generarea de pagini HTML, manuale sau PDF din fișierele RST.

Construirea documentației

Pentru a construi documentația folosind Sphinx, va trebui să rulați comanda make html la rădăcina folderului în care se află makefile.

face html

Ar trebui să vedeți fișierele HTML în folderul de compilare. Dacă au existat erori în timpul construirii, Sphinx vă va anunța în terminal.

Pentru a vizualiza documentația, deschideți fișierul index.html în browser:

Ar trebui să puteți naviga la ghidul de contribuție din cuprinsul.

Personalizarea documentației

În acest moment, documentația are un stil de bază. Dacă doriți să o personalizați, poate adăugând culorile mărcii dvs. sau chiar adăugând un mod întunecat, puteți instala și utiliza alte teme încorporate sau creați-vă propria temă personalizată.

Pentru a demonstra, încercați să schimbați tema cu cea numită natură:

  1. Deschideți fișierul de configurare Sphinx conf.py în directorul proiectului Sphinx.
  2. Căutați linia care definește opțiunea html_theme și schimbați-o în natură
  3. Salvați fișierul de configurare și reconstruiți documentația pentru a vedea modificările.

Așa ar trebui să arate pagina de pornire a documentației.

Dacă nu doriți să utilizați temele încorporate, puteți utiliza întotdeauna a temă Sphinx terță parte in schimb.

Documentarea codului dvs. folosind Docstrings

Sphinx generează documentația dvs. Python din textul pe care îl scrieți în fișierele RST. Deși acest lucru este suficient în unele cazuri, este posibil să doriți să utilizați șiruri de documente din codul dvs. la nivel de modul.

Docstrings trăiesc direct în fișierele sursă ale proiectului. Vă permit să descrieți ce face codul, să oferiți exemple și chiar să creați teste pentru acele exemple. Odată ce ați scris documente, puteți genera documentație din ele folosind Sphinx.