Почему я здесь?
Вы, читатель, пришли сюда потому, что написали на 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/conf.py
в своем любимом редакторе. Найдите узор#CHNAGEME#
и следуйте инструкциям. - Аналогичным образом отредактируйте файл
<your_project>/documentation/index.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->Source
и выберитеmaster branch/docs folder
Часть 6 - Поделитесь!
Ага. Вот и все. Подождите пару минут, пока GitHub обновится. Поделитесь своим красивым сайтом документации по адресу
https://<your_git_usrname>.github.io/<project_name>/
СОВЕТ: При обновлении документации необходимо удалить папку
docs
и создать ее заново. Подробнее см. Здесь.
Эпилог
Это та часть, где я говорю что-то вдумчивое о том, как замечательно создавать новый контент в мире. И какой вы замечательный человек, решив сделать свой исходный контент доступным, доступным и простым в использовании.
Но послушайте, вы прошли весь путь здесь, так что вы уже знаете это.
Так что, если есть еще что-то, чего вы все еще не знаете, я приглашаю вас посетить веб-сайт документации, который я сделал для этого руководства. Вы можете посмотреть мой доклад о Сфинксе. Надеюсь, они ответят на некоторые оставленные вами загадки о Сфинксе.