Използвайте Sphinx за създаване на документация в множество формати в CentOS 7

Sphinx е полезен инструмент, базиран на Python, за техници и писатели, който им позволява лесно да създават елегантна, напълно функционална документация в различни формати. Със Sphinx вие пишете документи, като използвате reStructuredText – лек език за маркиране – за начало, след което можете да получите изхода в множество формати, включително HTML, LaTeX, PDF, ePub и други.

В този урок ще покрием процеса на инсталиране и използване Sphinxна екземпляр на CentOS 7 x64 на платформата на Vult.

Предпоставки

• Инстанция на CentOS 7 x64.
• А потребителското Sudo .

Стъпка 1: Актуализирайте системата

sudo yum update
sudo shutdown -r now

Стъпка 2: Инсталирайте pip и Sphinx

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секцията: .. toctree:: :maxdepth: 2

   introduction
   chapter1
   chapter2
   chapter3
   more

Наложително е да:

• Оставете празен ред над въведеното.
• Не добавяйте суфикс към вашите изходни файлове с .rst.
• Поставете вашите изходни файлове в техния ред.
• Използвайте само едно име на файл на ред.
• Отстъпете имената на вашите файлове с :maxdepth: 2.

След като завършите промените си, запазете файла си и излезте от текстовия редактор.

ESC
:!wq

Стъпка 5: Създайте изходни файлове, посочени по-горе

index.rstИзходните файлове трябва да бъдат създадени с имена, които съответстват на това, което е посочено преди в , в противен случай те няма да бъдат включени в крайния изход.

Всички изходни файлове трябва да са съвместими с reStructuredText markup language. За повече информация, моля, вижте reStructuredText Primer .

Стъпка 6: Изведете HTML версията на вашата документация

След като приключите със съставянето на вашата документация, можете да изведете работата си, HTML format като изпълните командата по-долу:

make html

Резултатът ще бъде записан в директорията, ./\_build/htmlкоято включва всичко необходимо за преглед на файла в уеб сърфиране.

Това завършва нашия урок.