
Содержание статьи
Почему я здесь?
Вы, читатель, здесь, потому что написали какой-то отличный инструмент на Python, и хотите сделать его доступным и простым в использовании.
Я, писатель, здесь, потому что я был там, где вы находитесь несколько месяцев назад. Я хотел использовать пакет Sphinx для создания документации в стиле ReadTheDocs для своего проекта.
Я считаю, что подключение Sphinx нетривиально, поэтому я сделал это репозиторство GitHub, которое можно использовать как шаблон для ваш демонстрировать.
Прежде чем мы начнем, несколько основных предположений, чтобы убедиться, что мы на одной странице:
- Вы пишете на Python.
- Вы написали строки документов для фрагментов кода, которые вы хотите задокументировать.
- Ваша цель – создать документацию в стиле ReadTheDocs, которая, по крайней мере частично, будет автоматически создаваться сама.
- Вы знаете, что в Через 10 минут вы можете опубликовать первую версию вашей документации, это будет выглядеть примерно так:

Часть 1 – Оформление сцены
- Установите Sphinx:
pip install sphinx
- Перейдите на github.com/DalyaG/Sphinx185:
- Загрузите папку
documentation_template_for_your_next_project
- Скопируйте в свой проект
- Переименуйте папку
documentation

Часть 2 – Персонализация
- Откройте файл
<your_project>/documentation/c
onf.py в вашем любимом редакторе. Ищите папуttern #CHN
AGEME# и следуйте инструкциям. - Аналогично измените файл
<your_project>/documentation/ind
ex.rst и следуйте встроенным инструкциям.



Часть 3 – Добавьте нужное содержимое в документ
- Скажем, у вас есть файл Python с названием
my_amazing_class.py
который включает в себя класс, который вы хотите задокументировать. - В той же папке как
conf.py
иindex.rst
файлов, создайте новый файл под названиемmy_amazing_class.rst
и скопируйте-вставьте-персонализируйте этот шаблон:
This is a template for including classes========================================|.. autoclass:: my_amazing_class.MyAmazingClass|:ref:`Return Home <mastertoc>`
СОВЕТ: убедитесь, что папка, содержащая удивительный класс, находится в вашем
PYTHONPATH
и что он содержит файл инициализации__init__.py
- В
index.rst
файл, отредактируйте Содержимое, включив имя файла.rst
файл:
.. toctree:: :maxdepth: 1 :name: mastertoc
my_amazing_class
Часть 4 – «Скомпилировать»
- В терминале, внутри
documentation
папку, запуститьmake clean html
. - Это! Ваша первая версия документации готова к просмотру!
- Откройте файл
documentation/_build/html/index.html
в вашем браузере и убедитесь сами 🙂


Часть 5 — Размещение на страницах GitHub
- В корне вашего проекта откройте новую папку под названием
docs
и скопируйте в него содержимое<your_project>/documentation/_build
/html/ - Внутри этого нового
docs
папку, создайте пустой файл под названием.nojekyll
(Это указывает GitHub Pages обойти значение по умолчаниюJekyll
темы и используйтеHTML
иCSS
в вашем проекте) - Внесите изменения в
master
филиал. - В своем хранилище на GitHub перейдите к
Settings->GitHub Pages->
Источник
и сelect master branch/docs
папку


Часть 6 – Поделитесь!
Да. Это оно. Подождите пару минут, пока GitHub обновится. Поделитесь своим прекрасным сайтом с документацией по адресу
https://<your_git_usrname>.github.io/<proje
ct_name>/
СОВЕТ: При обновлении документации необходимо удалить файл
docs
папку и создайте ее снова. Детальнее смотрите здесь.
Эпилог
В этой части я говорю о том, как отлично создавать новый контент в мире. И какой замечательный человек, что вы решили сделать свое оригинальное содержимое доступным, доступным и простым в использовании.
Но эй, ты прошел весь путь сюда, и ты уже знаешь об этом.
Итак, если есть что-то другое, о чем вы все еще считаете, что не знаете, я приглашаю вас просмотреть веб-сайт документации, созданный я для этого учебника. Вы можете посмотреть доклад, который я говорил о Сфинксе. Надеемся, это ответит на некоторые загадки, которые вы оставили о Сфинксе.