Документация - это настоящий проект, но ваш проект уже является проектом, а кому нужен другой проект?
Мы начнем с совершенно пустого проекта и перейдем к веб-сайту, размещенному на страницах GitHub, который создается автоматически с помощью действий GitHub.
Здесь вы можете увидеть окончательный результат.
Вы можете найти весь код этого проекта на GitHub здесь.
Ваша библиотека
Я сказал, что мы сделаем это с нуля, поэтому нам придется сделать библиотеку. У вас, вероятно, уже есть библиотека, поэтому вы можете легко понять, как вставить сюда свои файлы, и перейти к следующему разделу.
Давайте создадим библиотеку под названием autos. Создайте для него папку и два файла:
mkdir autos touch autos/__init__.py touch autos/bike.py
с содержанием для bike.py:
и файл __init__.py:
from .bike import *
Также добавим тест tests/test.py в отдельный каталог:
Наконец, давайте превратим этот пакет в настоящий, добавив setup.py. Вы можете использовать генератор или просто украсть генератор по умолчанию с package.python.org - создать setup.py с содержимым:
Очевидно, отредактируйте его по своему усмотрению. Здесь вам также понадобится README.md в качестве long_description (и потому что) это хорошая практика:
touch README.md
Окончательная структура каталогов должна выглядеть так:
autos/__init__.py autos/bike.py setup.py README.md
Теперь вы можете установить библиотеку
pip install .
Тестовый сценарий в каталоге tests должен выдать:
Riding: SR400 on road: 101
Большой! Переходим к документации.
Добавление документации
Начнем с добавления документации. Если вы используете VS Code (а вы должны быть!), Вы можете использовать Python Docstring Generator, чтобы помочь вам.
Сначала добавьте typing объявлений ко всем аргументам метода и возвращаемым значениям:
Некоторые другие распространенные типы:
List, e.g.List[int].Tuple, e.g.Tuple[str,float].Dict, e.g.Dict[str,int].Union, напримерUnion[int,None]может бытьintилиNone.
Перейдите под одну из сигнатур метода и введите ”””. Он должен предложить строку документации:
Затем нажмите Enter для автозаполнения документации:
Заполните некоторую документацию, например:
Примечательно то, что редактирование test.py в любой современной среде IDE (например, VS Code) теперь дает вам предложения автозаполнения:
Создание веб-сайта
Вам необходимо установить Sphinx:
pip install -U sphinx
Если вы используете Ubuntu, возможно, вместо этого вам понадобится:
sudo apt-get install python3-sphinx
Создадим новую docs папку:
mkdir docs cd docs
Используйте sphinx-quickstart, чтобы начать:
sphinx-quickstart
Выберите все значения по умолчанию, например no для > Separate source and build directories (y/n) [n]:. В качестве названия проекта я выбрал autos.
Теперь в папке docs должно быть:
_build/ _static/ _templates/ conf.py index.rst make.bat Makefile
Makefile, очевидно, используется для сборки проекта. conf.py указывает сборку, а index.rst - точка входа на веб-сайт.
Чтобы сделать сайт, запустите:
make html
Чтобы сделать разные цели, попробуйте просто make перечислить все возможные цели. Полученные страницы будут в _build/html. Страница по умолчанию выглядит так:
Мне всегда нравилась тема ReadTheDocs]. Идите и установите его:
pip install sphinx-rtd-theme
Давайте добавим его в конфигурацию в conf.py. Добавьте оператор импорта, а остальные добавьте:
Теперь получаем:
Так выглядит лучше! Но у нас еще нет строк документации, которые мы написали на Python.
Автоматическое создание файлов RST
Преобразование строк документа в документацию осуществляется с помощью расширения sphinx.ext.autodoc, как описано здесь. Продолжайте и добавьте его в список расширений в conf.py:
extensions = [ “sphinx_rtd_theme”, “sphinx.ext.autodoc” ]
Чтобы определенные классы появились в документации, должен существовать файл RST, ссылающийся на них. Пример фрагмента в файле .rst может выглядеть так:
.. automodule:: autos.bike :members: :undoc-members: :show-inheritance:
что показывает, что здесь должен быть задокументирован класс autos.bike. Если вы никогда раньше не писали RST, обратите внимание, что он очень чувствителен к пространству и отступам!
Давайте автоматически сгенерируем их. Изнутри каталога docs запустите:
sphinx-apidoc -o . ../autos
Здесь -o . указывает, что текущий docs каталог является выходным, а ../autos указывает исходный каталог. Получаем два новых файла:
autos.rst modules.rst
с содержимым для autos.rst (примечание: возможно, вам придется просмотреть их в необработанном формате!):
а для modules.rst содержит текущий список модулей:
Наконец, нам нужно подключить эти новые файлы к исходному index.rst. Добавьте ссылку на modules.rst в index.rst:
Снова запустите команду make:
make html
получить следующее:
Это почти сработало. Мы замечаем, что в документации по классам отсутствуют строки документации для конструктора!
По какой-то замечательной причине метод __init__ по умолчанию пропускается! Давайте исправим это с помощью этой уловки. Добавьте следующий фрагмент в conf.py внизу:
Восстановите, предварительно убедившись в чистоте:
make clean html make html
и вы должны обнаружить, что конструктор теперь задокументирован:
Размещение документации на GitHub
Начните с инициализации репозитория git с git init . для папки с содержимым:
autos/ docs/ tests/ setup.py README.md
Вы также должны использовать .gitignore как минимум с:
__pycache__/ .DS_Store docs/_build/ docs/_static/ docs/_templates
Зафиксируйте оставшиеся файлы в репо, затем перейдите на GitHub, создайте новое репо для этого проекта и отправьте свою первую фиксацию.
git add . git commit -m “Initial” git remote add origin https://github.com/... git push — set-upstream origin master
Давайте создадим новый рабочий процесс GitHub Actions. Они живут в каталоге .github/workflows, которого еще не существует. Создать это:
mkdir .github/ mkdir .github/workflows touch .github/workflows/docs.yml open .github/workflows/docs.yml
Дайте файлу следующее содержимое:
Давайте разберемся:
name- очевидноon- сюда можно добавлять разные триггеры. Здесь мы создаем документацию для каждого шага к освоению. Вы также можете сделать, например, запрос на вытягивание.docs job- это единственное задание, которое будет собирать документы.runs-on: ubuntu-latest- Вы можете выбрать из пары разных бегунов, кромеubuntu-latest, как описано здесь.uses: actions/checkout@v2- очень важно! Без этого мы фактически не проверяем наше репо!Install Python- установите последнюю версию Python 3.8 - оказывается,ubuntu-latestне самая последняя версия.Build docs— предыдущая командаmake html. Убедитесь, что мы делаем это в каталоге docs.Deploy- разверните страницы вdocs/_build/htmlв веткеgh-pages, чтобы ваши документы стали доступны для всех.
Добавьте, зафиксируйте и продвиньте рабочий процесс. Вы можете отслеживать ход выполнения действия на своей странице репо в разделе Actions.
После этого ваш веб-сайт должен быть доступен по адресу:
https://username.github.io/repo_name
Моя появилась не сразу. Проверьте свои настройки на вкладке «Настройки» в разделе «Страницы GitHub» - они должны были автоматически измениться на сборку из ветки gh-pages:
Мне пришлось вручную изменить это значение с gh-pages на master и обратно, чтобы сайт стал доступен. Затем он также должен автоматически указать здесь URL-адрес.
Вы также можете проверить свою ветку gh-pages, которая должна содержать ваши HTML-файлы:
Распространенная проблема в процессе сборки заключается в том, что вы использовали некоторую внешнюю библиотеку, которую вы установили с pip install external_library. Что теперь - следует ли добавить его в процесс сборки документации? Нет - это только добавляет дополнительные зависимости, которые необходимо установить, и, вероятно, не имеет отношения к документации. Вместо этого вы можете отредактировать conf.py параметр:
autodoc_mock_imports = [ “external_library" ]
так что процесс сборки документов будет продолжаться, даже если библиотека отсутствует.
Заключительные мысли
Ваши последние документы теперь онлайн и создаются каждый раз, когда вы переходите к мастеру!
Наконец, мы можем завершить это руководство, добавив к вашему README.md значок, созданный вашими документами:
Спасибо за прочтение!
