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

kak legko zadokumentirovat svoj kod

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

Вы, читатель, здесь, потому что написали какой-то отличный инструмент на Python, и хотите сделать его доступным и простым в использовании.

Я, писатель, здесь, потому что я был там, где вы находитесь несколько месяцев назад. Я хотел использовать пакет Sphinx для создания документации в стиле ReadTheDocs для своего проекта.

Я считаю, что подключение Sphinx нетривиально, поэтому я сделал это репозиторство GitHub, которое можно использовать как шаблон для ваш демонстрировать.

Прежде чем мы начнем, несколько основных предположений, чтобы убедиться, что мы на одной странице:

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

Часть 1 – Оформление сцены

  • Установите Sphinx: pip install sphinx
  • Перейдите на github.com/DalyaG/Sphinx185:
  • Загрузите папку documentation_template_for_your_next_project
  • Скопируйте в свой проект
  • Переименуйте папку documentation
CYOS9MopVTLHOshtpGkqwYFcddBNWui4WMNx

Часть 2 – Персонализация

  • Откройте файл <your_project>/documentation/conf.py в вашем любимом редакторе. Ищите папуttern #CHNAGEME# и следуйте инструкциям.
  • Аналогично измените файл <your_project>/documentation/index.rst и следуйте встроенным инструкциям.
zx3u0k2vQCGT5NKfSvks3flwgONlK4vi72U8
n6a72jLWaFOwE1Dc0ip6CT2K-3Bqp9gD43B0
36Kf81INhsKdDkppxQCbETPtFzbUI2C07dFn

Часть 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 в вашем браузере и убедитесь сами 🙂
fX7yeyvLr8pcpDbciN9zlmsDcBmm2A36Z96L
SGc77JLWj9RwwUjzNO1RfZSd-UF5wL-QlWza

Часть 5 — Размещение на страницах GitHub

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

Часть 6 – Поделитесь!

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

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

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

Эпилог

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

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

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

Добавить комментарий

Ваш адрес email не будет опубликован.