Как да настроите Sphinx да документира вашия Python код

Sphinx е един от най-популярните инструменти за генериране на документация. В цялата общност на Python разработчиците използват този безплатен софтуер с отворен код. Той може да извлича текст директно от вашия код или файлове за маркиране и след това да го използва за генериране на документация в различни формати като обикновен текст, HTML, PDF и EPUB.

Настройка на Sphinx

Преди да настроите Sphinx, вижте какво прави и някои от основните му функции.

Какво е Sphinx и какво прави?

Както споменахме, Sphinx е генератор на документация. По подразбиране той използва езика за маркиране reStructuredText (RST), но чрез разширения на трети страни може също използвайте Markdown, популярния език за маркиране на обикновен текст. След това преобразува тези RST или Markdown файлове в HTML, PDF, ръчни страници или други формати, които предпочитате.

Някои от функциите, които Sphinx включва са:

• Възможност за генериране на документация от код.
• Възможност за кръстосани препратки към различни страници на документи с помощта на автоматични връзки за функции, класове, цитати и термини от речника.
• Осветяване на синтаксиса за кодови блокове.
• Поддръжка за теми, които могат да променят облика и усещането на документите.
• Лесно дефиниране на дървото на документа чрез таблица със съдържание.
• Възможност за интегриране с разширения на трети страни за добавяне на повече функционалност към документите, като тестване на кодови фрагменти.

Инсталиране на Sphinx

Преди да инсталирате Sphinx, уверете се, че имате Python 3 е инсталиран във вашата среда за разработка. След това можете да използвате мениджъра на pip пакети, за да инсталирате Sphinx, като изпълните следната команда във вашия терминал:

pip инсталирате сфинкс

Това ще изтегли и инсталира Sphinx и неговите зависимости.

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

sphinx-build --версия

Ако всичко работи добре, трябва да видите номера на версията за пакета Sphinx, който току-що сте инсталирали.

Създаване на нов проект за сфинкс

След като инсталирате Sphinx, отидете до вашата работна директория и изпълнете командата sphinx-quickstart, за да създадете нов проект Sphinx.

сфинкс-бърз старт

Тази команда ще ви подкани да отговорите на поредица от въпроси за това как да конфигурирате вашия проект Sphinx. Можете да посочите името на проекта и да използвате опциите по подразбиране за другите въпроси. В бъдеще може да искате да персонализирате отговорите въз основа на вашия проект.

Ако изброите съдържанието на вашата директория, ще видите, че тази команда създава някои файлове за вас. Conf.py съдържа конфигурационните стойности, а index.rst служи като начална страница на вашата документация. Директорията за изграждане ще бъде домакин на генерираната документация и Sphinx използва Makefile (make.bat в Windows), за да изгради документацията.

Писане на документация с помощта на Sphinx

Файлът index.rst в корена на вашата директория е началната страница на вашето приложение. Така че, отворете го с текстов редактор като VS Code—или всеки друг добър, безплатен редактор на код- за да го редактирате.

Можете да промените index.rst, както сметнете за добре, но едно нещо, което поне трябва да има, е директивата root toctree (дърво на съдържанието). Това е от съществено значение, тъй като свързва множество файлове в една йерархия от документи.

За да добавите документация към файла index.rst, можете да използвате RST маркирането.

Като пример, разгледайте файл index.rst за модула math_utils. Този файл може да включва кратък преглед на предназначението на модула и съдържание, което препраща към други страници от документацията.

Добре дошли в Math Utils
.. toctree::
 :maxdepth: 2
Приготвяме се да започнем

За да използвате този модул, ще ви трябва следното:
* Инсталиран Python.
* Текстов редактор
Математически помощни средства

Модулът `math-utils` предоставя основни математически функции като събиране и
изваждане.

Можете да добавите още .rst файлове, ако е необходимо. Например, можете да създадете ръководство за принос във файл с име contributing.rst, съдържащ следните насоки за принос.

Ръководство за принос
Приветстваме приноса към нашия проект! Ето някои насоки за
допринасящ:
- Разклонете проекта в GitHub.
- Направете вашите промени в нов клон.
- Напишете тестове, за да сте сигурни, че промените ви работят правилно.
- Изпратете заявка за изтегляне с вашите промени.
- Направете всички поискани промени.
Благодарим ви за приноса!

След това можете да свържете този файл от index.rst, като добавите нов раздел към директивата toctree:

.. toctree::
 :maxdepth: 2
 :caption: Съдържание

 допринасящи

Това създава нов елемент с име contributing в съдържанието, който при щракване отвежда потребителя до страницата за принос.

След като напишете документацията, следващата стъпка е да я изградите. Тук изграждането на документацията означава генериране на HTML, ръчни или PDF страници от RST файловете.

Изграждане на документацията

За да изградите документацията с помощта на Sphinx, ще трябва да изпълните командата make html в корена на вашата папка, където се намира makefile-ът.

направи html

Трябва да видите HTML файловете в папката за изграждане. Ако е имало грешки по време на изграждането, Sphinx ще ви уведоми в терминала.

За да видите документацията, отворете файла index.html във вашия браузър:

Трябва да можете да навигирате до ръководството за принос от съдържанието.

Персонализиране на документацията

В момента документацията има някакъв основен стил. Ако искате да го персонализирате, може би като добавите цветове на вашата марка или дори добавите тъмен режим, можете да инсталирате и използвате други вградени теми или създайте своя собствена персонализирана тема.

За да демонстрирате, опитайте да промените темата на тази, наречена природа:

1. Отворете конфигурационния файл на Sphinx conf.py във вашата директория на проекта Sphinx.
2. Потърсете реда, който дефинира опцията html_theme и я променете на природа
3. Запазете конфигурационния файл и изградете отново документацията, за да видите промените си.

Ето как трябва да изглежда началната страница на документацията.

Ако не искате да използвате вградените теми, винаги можете да използвате a тема Sphinx на трета страна вместо.

Документиране на вашия код с помощта на Docstrings

Sphinx генерира вашата Python документация от текст, който пишете в RST файлове. Въпреки че това е достатъчно в някои случаи, може също да искате да използвате документни низове във вашия код към него на ниво модул.

Документните низове живеят директно в изходните файлове на вашия проект. Те ви позволяват да опишете какво прави кодът, да предоставите примери и дори да създадете тестове за тези примери. След като напишете документни низове, можете да генерирате документация от тях с помощта на Sphinx.