Как легко задокументировать свой код

Содержание статьи

Почему я здесь?

Вы, читатель, здесь, потому что написали какой-то отличный инструмент на 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 в вашем любимом редакторе. Ищите папуttern #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->Источник
и сelect master branch/docs папку

Да. Это оно. Подождите пару минут, пока GitHub обновится. Поделитесь своим прекрасным сайтом с документацией по адресу

https://<your_git_usrname>.github.io/<project_name>/

СОВЕТ: При обновлении документации необходимо удалить файл docs папку и создайте ее снова. Детальнее смотрите здесь.

Эпилог

В этой части я говорю о том, как отлично создавать новый контент в мире. И какой замечательный человек, что вы решили сделать свое оригинальное содержимое доступным, доступным и простым в использовании.

Но эй, ты прошел весь путь сюда, и ты уже знаешь об этом.

Итак, если есть что-то другое, о чем вы все еще считаете, что не знаете, я приглашаю вас просмотреть веб-сайт документации, созданный я для этого учебника. Вы можете посмотреть доклад, который я говорил о Сфинксе. Надеемся, это ответит на некоторые загадки, которые вы оставили о Сфинксе.