Notaðu Sphinx til að búa til skjöl á mörgum sniðum á CentOS 7

Sphinx er gagnlegt Python-undirstaða tól fyrir tæknimenn og rithöfunda sem gerir þeim kleift að búa til glæsilega, fullkomlega hagnýta skjöl á ýmsum sniðum. Með Sphinx skrifar þú skjöl með því að nota reStructuredText - létt álagningarmál - til að byrja með, þá geturðu fengið úttakið á mörgum sniðum, þar á meðal HTML, LaTeX, PDF, ePub og fleira.

Í þessari kennslu munum við fjalla um ferlið við að setja upp og nota Sphinxá CentOS 7 x64 tilviki á vettvangi Vult.

Forkröfur

• CentOS 7 x64 tilvik.
• A sudo notandi .

Skref 1: Uppfærðu kerfið

sudo yum update
sudo shutdown -r now

Skref 2: Settu upp pip og Sphinx

sudo yum install -y python-devel python-setuptools python-pip
sudo pip install --upgrade pip
sudo pip install -U Sphinx

Skref 3: Settu upp grunnstillingar fyrir skjölin þín

Áður en þú byrjar að nota Sphinxþarftu að tilgreina upprunaskrána þína sem Sphinxmun keyra og vista öll skjölin þín. Þegar þú hefur búið til möppuna sem þú ætlar að nota geturðu keyrt sphinx-quickstartsem mun frumstilla Sphinxog búa til nauðsynlegar grunnstillingar.

sphinx-quickstart er svipað og uppsetningarhjálp sem mun hvetja þig með spurningum sem ákvarða þætti verkefnisins.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Skref 4: Búðu til stigveldið fyrir skjölin þín

Sjálfgefið mun sphinx-quickstarttöframaðurinn búa til nokkrar möppur og skrár.

_build           # The directory for containing Sphinx output
conf.py          # The file containing your project configurations
index.rst        # The master file containing the hierarchy of your documentation
make.bat         # A Windows command file
Makefile         # A file necessary for running the make command
_static          # The directory for static files, including custom stylesheets, pictures, etc.
_templates       # The directory for custom templates

Við skulum skoða aðalskrána, index.rst, sem inniheldur stigveldi skjalanna þinna; nefnilega efnisyfirlitstréð eða toctree.

Opnaðu það með textaritli:

vi index.rst

Þegar þú skoðar skrána muntu taka eftir hluta sem heitir toctree. Ef þú ert með aðrar frumskrár ( *.rst) fyrir skjölin þín þarftu að tilgreina þær í toctreehlutanum: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Það er mikilvægt að:

• Skildu eftir auða röð fyrir ofan inntakið þitt.
• Ekki bæta frumskránum þínum við .rst.
• Settu upprunaskrárnar þínar í viðkomandi röð.
• Notaðu aðeins eitt skráarnafn í hverri röð.
• Dragðu inn skráarnöfnin þín með :maxdepth: 2.

Þegar þú hefur lokið við breytingar þínar skaltu vista skrána þína og hætta í textaritlinum.

ESC
:!wq

Skref 5: Búðu til upprunaskrár sem tilgreindar eru hér að ofan

Frumskrárnar verða að vera búnar til með nöfnum sem passa við það sem áður var tilgreint í index.rst, annars verða þær ekki teknar með í lokaúttakinu.

Allar frumskrár verða að vera samhæfar við reStructuredText markup language. Fyrir frekari upplýsingar, vinsamlegast skoðaðu reStructuredText Primer .

Skref 6: Gefðu út HTML útgáfuna af skjölunum þínum

Þegar þú hefur lokið við að semja skjölin þín geturðu sent verkið þitt út HTML format með því að framkvæma skipunina hér að neðan:

make html

Úttakið verður vistað í möppunni ./\_build/htmlsem inniheldur allt sem þarf til að skoða skrána í vefskoðun.

Þetta lýkur kennslunni okkar.