Загадка Сфинкса: как можно легко документировать свой код

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

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

Я, писатель, я здесь, потому что я был прав, где ты несколько месяцев назад. Я хотел использовать Сфинкс Пакет, чтобы сделать документацию по программам readTheDocs для моего проекта.

Я нашел борту сфинкса, нетривиальных, поэтому я сделал Этот Github Repo которые могут быть использованы в качестве шаблона для Ваш проект.

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

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

Часть 1 – Установка сцены

Установить Сфинкс: PIP Установить Сфинкс
Перейти к github.com/dalyag/sphinx185 :
Скачать папку Документация_template_for_your_next_project.
Скопируйте в свой проект
Переименуйте папку документация

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

Откройте файл /Документация/C onf.py в вашем любимом редакторе. Поиск PA Тернтер #чн Ageme # и следуйте инструкциям.
Точно так же отредактируйте файл /Документация/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 `

В index.rst Файл, отредактируйте оглавление, чтобы включить имя .rst файл:

.. toctree::   :maxdepth: 1   :name: mastertoc

   my_amazing_class

Часть 4 – «Компиляция»

В терминале внутри Документация Папка, запустить сделать чистый HTML Отказ
Это оно! У вас есть первая версия вашей документации, готовой к просмотру!
Откройте файл Документация/_build/html/index.html В вашем браузере и посмотрите на себя:)

Часть 5 – хозяин на страницах GitHub

Под корнем вашего проекта открыть новую папку под названием Документы и копировать внутри него содержание /Документация/_Build /html/
Внутри этого нового Документы Папка, создайте пустой файл под названием .nojekyll (Это говорит о страницах GitHub обходить по умолчанию jekyll темы и используют HTML и CSS в вашем проекте)
Нажмите свои изменения в Мастер ветка.
В вашем репозитории на Github перейдите в Настройки-> Страницы GitHub-> Источник и S Избрать Мастер Филиал/Документы папка

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

Ага. Вот и все. Подождите пару минут для Github, чтобы обновить. Поделитесь своей прекрасной документацией сайта в

https:// .github.io/ CT_NAME>/

Эпилог

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

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

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