Користите Спхинк за креирање документације у више формата на ЦентОС 7

Спхинк је користан алат заснован на Питхон-у за техничаре и писце који им омогућава да лако креирају елегантну, потпуно функционалну документацију у различитим форматима. Са Спхинк-ом пишете документе користећи реСтруцтуредТект – лагани језик за означавање – за почетак, а затим можете добити излаз у више формата, укључујући ХТМЛ, ЛаТеКс, ПДФ, еПуб и друге.

У овом водичу ћемо покрити процес инсталирања и коришћења Sphinxна инстанци ЦентОС 7 к64 на Вултовој платформи.

Предуслови

• Инстанца ЦентОС 7 к64.
• : Судо корисника .

Корак 1: Ажурирајте систем

sudo yum update
sudo shutdown -r now

Корак 2: Инсталирајте пип и Спхинк

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

Корак 3: Подесите основну конфигурацију за вашу документацију

Пре него што почнете да користите Sphinx, потребно је да наведете свој изворни директоријум у коме Sphinxће се покретати и чувати сва ваша документација. Када креирате директоријум који намеравате да користите, можете покренути sphinx-quickstartкоји ће иницијализовати Sphinxи креирати потребну основну конфигурацију.

sphinx-quickstart је сличан чаробњаку за подешавање који ће вам поставити питања која одређују аспекте вашег пројекта.

cd ~
mkdir doc1
cd doc1
sphinx-quickstart

Корак 4: Направите хијерархију за своју документацију

Подразумевано, sphinx-quickstartчаробњак ће креирати неколико директоријума и датотека.

_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

Хајде да погледамо главни фајл, index.rst, који садржи хијерархију ваше документације; наиме, стабло садржаја или toctree.

Отворите га помоћу уређивача текста:

vi index.rst

Док прегледате датотеку, приметићете одељак под називом toctree. Ако имате друге изворне датотеке ( *.rst) за вашу документацију, мораћете да их наведете у toctreeодељку: .. тоцтрее:: :макдептх: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Императив је да се:

• Оставите празан ред изнад уноса.
• Не стављајте суфикс у изворне датотеке са .rst.
• Поставите своје изворне датотеке по њиховом редоследу.
• Користите само једно име датотеке по реду.
• Увуците називе датотека са :maxdepth: 2.

Када завршите са изменама, сачувајте датотеку и изађите из уређивача текста.

ESC
:!wq

Корак 5: Креирајте изворне датотеке наведене изнад

Изворне датотеке морају бити креиране са именима која одговарају ономе што је претходно наведено у index.rst, иначе неће бити укључене у коначни излаз.

Све изворне датотеке морају бити компатибилне са reStructuredText markup language. За више информација погледајте реСтруцтуредТект Пример .

Корак 6: Изнесите ХТМЛ верзију ваше документације

Када завршите са састављањем своје документације, можете извести свој рад HTML format тако што ћете извршити наредбу у наставку:

make html

Излаз ће бити сачуван у директоријуму ./\_build/htmlкоји укључује све што је потребно за прегледање датотеке у веб прегледању.

Овим је наш водич завршен.