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

Вы, читатель, пришли сюда потому, что написали на 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 и создать ее заново. Подробнее см. Здесь.

Эпилог

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

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

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