Išnaudokite visas projekto dokumentų galimybes – naudokite Sphinx, kad sukurtumėte patrauklią, išsamią HTML dokumentaciją.

Sfinksas yra vienas iš populiariausių dokumentų generavimo įrankių. Visoje Python bendruomenėje kūrėjai naudoja šią nemokamą atvirojo kodo programinę įrangą. Jis gali išgauti tekstą tiesiai iš jūsų kodo arba žymėjimo failų ir naudoti jį įvairių formatų dokumentams, pvz., paprastu tekstu, HTML, PDF ir EPUB, kurti.

Sfinkso nustatymas

Prieš nustatydami „Sfinksą“, pažiūrėkite, ką jis veikia ir kai kurias pagrindines jo funkcijas.

Kas yra Sfinksas ir ką jis veikia?

Kaip minėta, Sfinksas yra dokumentų generatorius. Pagal numatytuosius nustatymus ji naudoja reStructuredText (RST) žymėjimo kalbą, bet per trečiųjų šalių plėtinius taip pat gali naudokite Markdown, populiarią paprasto teksto žymėjimo kalbą. Tada jis konvertuoja šiuos RST arba žymėjimo failus į HTML, PDF, vadovo puslapius ar kitus pageidaujamus formatus.

Kai kurios „Sfinkso“ funkcijos yra šios:

  • Galimybė generuoti dokumentus iš kodo.
    • instagram viewer
  • Galimybė daryti kryžmines nuorodas į skirtingus dokumento puslapius naudojant automatines funkcijų, klasių, citatų ir žodyno terminų nuorodas.
  • Sintaksės paryškinimas kodo blokams.
  • Temų, kurios gali pakeisti dokumentų išvaizdą ir pojūtį, palaikymas.
  • Lengvas dokumentų medžio apibrėžimas naudojant turinį.
  • Galimybė integruoti su trečiųjų šalių plėtiniais, kad dokumentams būtų suteikta daugiau funkcijų, pvz., testavimo kodo fragmentai.

Sfinkso diegimas

Prieš diegdami Sphinx, įsitikinkite, kad turite Python 3 įdiegta jūsų kūrimo aplinkoje. Tada galite naudoti pip paketų tvarkyklę, kad įdiegtumėte Sphinx, terminale vykdydami šią komandą:

pip įdiegti sfinksą

Tai atsisiųs ir įdiegs Sphinx ir jo priklausomybes.

Įdiegę komandų eilutėje paleiskite toliau nurodytus veiksmus.

sphinx-build -- versija

Jei viskas veikė gerai, turėtumėte pamatyti ką tik įdiegto Sphinx paketo versijos numerį.

Naujo Sfinkso projekto kūrimas

Įdiegę Sphinx, eikite į savo darbo katalogą ir paleiskite komandą sphinx-quickstart, kad sukurtumėte naują Sfinkso projektą.

sfinksas-greitas startas

Ši komanda paragins jus atsakyti į keletą klausimų, kaip sukonfigūruoti savo Sphinx projektą. Galite nurodyti projekto pavadinimą ir naudoti numatytąsias parinktis kitiems klausimams. Ateityje galbūt norėsite tinkinti atsakymus pagal savo projektą.

Jei išvardinsite savo katalogo turinį, pamatysite, kad ši komanda už jus sukuria kai kuriuos failus. Conf.py yra konfigūracijos reikšmės, o index.rst yra jūsų dokumentacijos pasveikinimo puslapis. Sukurta dokumentacija bus talpinama kūrimo kataloge, o Sphinx dokumentacijai kurti naudoja Makefile (make.bat sistemoje Windows).

Dokumentacijos rašymas naudojant Sfinksą

Failas index.rst jūsų katalogo šaknyje yra jūsų programos pagrindinis puslapis. Taigi atidarykite jį naudodami teksto rengyklę, pvz., „VS Code“ arba bet koks kitas geras nemokamas kodo redaktorius– redaguoti.

Galite pakeisti index.rst, kaip jums atrodo tinkama, tačiau bent vienas dalykas, kurį ji turėtų turėti, yra šakninio toctree (turinio medžio) direktyva. Tai būtina, nes sujungia kelis failus į vieną dokumentų hierarchiją.

Norėdami įtraukti dokumentus į failą index.rst, galite naudoti RST žymėjimą.

Kaip pavyzdį apsvarstykite modulio math_utils failą index.rst. Šiame faile gali būti trumpa modulio paskirties apžvalga ir turinys, nurodantis kitus dokumentacijos puslapius.

Sveiki atvykę į Math Utils
.. toctree::
 :maksimalus gylis: 2


Darbo pradžia


Norėdami naudoti šį modulį, jums reikės šių dalykų:


* Įdiegtas Python.


* Teksto rengyklė


Math Utils


Modulis „math-utils“ teikia pagrindines matematikos funkcijas, tokias kaip pridėjimas ir
atimti.

Jei reikia, galite pridėti daugiau .rst failų. Pavyzdžiui, galite sukurti indėlio vadovą faile, pavadintame contributing.rst, kuriame yra šios įnašo gairės.

Prisidėjimo vadovas
Kviečiame prisidėti prie mūsų projekto! Štai keletas gairių
prisideda:


- Paleiskite projektą „GitHub“.
- Atlikite pakeitimus naujame filiale.
- Parašykite testus, kad įsitikintumėte, jog pakeitimai veikia tinkamai.
– Pateikite ištraukimo užklausą su pakeitimais.
- Atlikite visus prašomus pakeitimus.
Dėkojame, kad prisidėjote!

Tada galite susieti šį failą iš index.rst pridėdami naują skyrių prie toctree direktyvos:

.. toctree::
 :maksimalus gylis: 2
 :caption: Turinys

 prisidedant

Taip turinyje sukuriamas naujas elementas, pavadintas indėlis, kurį spustelėjus vartotojas nukreipiamas į indėlio puslapį.

Kai parašysite dokumentaciją, kitas žingsnis yra sukurti. Čia dokumentacijos kūrimas reiškia HTML, vadovo arba PDF puslapių generavimą iš RST failų.

Dokumentacijos kūrimas

Norėdami sukurti dokumentaciją naudodami Sphinx, aplanko, kuriame yra makefile, šaknyje turėsite paleisti komandą make html.

padaryti html

Turėtumėte pamatyti HTML failus kūrimo aplanke. Jei kūrimo metu įvyko klaidų, Sfinksas apie tai praneš terminale.

Norėdami peržiūrėti dokumentaciją, naršyklėje atidarykite failą index.html:

Turėtumėte turėti galimybę naršyti į pridedamą vadovą iš turinio.

Dokumentacijos pritaikymas

Šiuo metu dokumentacija turi tam tikrą pagrindinį stilių. Jei norite jį tinkinti, galbūt pridėdami savo prekės ženklo spalvas ar net pridėdami tamsųjį režimą, galite įdiegti ir naudoti kitas integruotos temos arba sukurkite savo pasirinktinę temą.

Norėdami parodyti, pabandykite pakeisti temą į tą, kuri vadinama gamta:

  1. Atidarykite Sphinx konfigūracijos failą conf.py savo Sphinx projekto kataloge.
  2. Ieškokite eilutės, apibrėžiančios parinktį html_theme, ir pakeiskite ją į prigimtį
  3. Išsaugokite konfigūracijos failą ir perkurkite dokumentaciją, kad pamatytumėte pakeitimus.

Taip turėtų atrodyti pagrindinis dokumentacijos puslapis.

Jei nenorite naudoti integruotų temų, visada galite naudoti a trečiosios šalies Sfinkso tema vietoj to.

Kodo dokumentavimas naudojant dokumentų eilutes

Sphinx sukuria jūsų Python dokumentaciją iš teksto, kurį rašote RST failuose. Nors kai kuriais atvejais to pakanka, galbūt norėsite naudoti kodo dokumentų eilutes modulio lygiu.

Dokumentų eilutės yra tiesiogiai jūsų projekto šaltinio failuose. Jie leidžia apibūdinti, ką daro kodas, pateikti pavyzdžių ir netgi sukurti tų pavyzdžių testus. Kai parašysite dokumentų eilutes, galite iš jų sukurti dokumentus naudodami Sphinx.