Как добавить бесплатную онлайн-документацию в ваш проект Python?

Python

1. Sphinx и прочитайте документы

1.1 Sphinx

Sphinx — мощный генератор документации со множеством мощных функций для написания технической документации, в том числе:

  • Поддерживайте исходный документ, создавайте веб-страницы, PDF-файлы для печати, документы для электронных читателей (ePub) и т. д.
  • Поддержка reStructuredText или Markdown для написания документов
  • Широко используемая система документирования кода
  • Подсветка синтаксиса примера кода
  • Активная официальная и сторонняя экосистема расширений

1.2 Read the Docs

«Read the Docs» предоставляет автоматизированные сборки, контроль версий и онлайн-хостинг, чтобы упростить публикацию документации по программному обеспечению и управление ею. Он использует Sphinx для генерации статических html-страниц, авторизуется через учетную запись github и автоматически завершает генерацию и онлайн-обновление документов, когда локальный проект отправляется в репозиторий github.

1.3 Отношения между ними

Вы можете просто думать о Sphinx как об автономном инструменте для создания документации, который поддерживает различные темы, а Read the Docs — это бесплатная онлайн-платформа для размещения документации, которая использует Sphinx в качестве инструмента для создания документации и предоставляет свои собственные темы. Отношения между ними аналогичны jekyll и GitHub Pages.

2. Установка

2.1 Установка Сфинкса

pip install sphinx

2.2 Установите тему Read the Docs

pip install sphinx_rtd_theme

* 2.3 Установите расширение Sphinx Markdown

По умолчанию для написания документов используется reStructuredText (.rst), для поддержки Markdown (.md) необходимо установить это расширение.

pip install recommonmark

3. Добавьте документацию в существующий проект

Реальный проект автора размещен на GitHubimgkernelНапример. Читатели модифицируют соответствующие части своими реальными проектами, которые не будут описаны отдельно ниже.

3.1 Создайте каталог документов в корневом каталоге проекта

Клонируйте проект:

git clone https://github.com/kenblikylee/imgkernel.git
cd imgkernel

Создайте и переключитесь наdocsФилиал:

git checkout -b docs

Создать подкаталогиdocs:

mkdir docs

3.2 Использованиеsphinx-quickstartИнициализировать документ

Входитьdocsкаталог, запустите командуsphinx-quickstart:

cd docs
sphinx-quickstart

Справочник по конфигурации опции:

> Separate source and build directories (y/n) [n]: y
> Name prefix for templates and static dir [_]:
> Project name: imgkernel
> Author name(s): ken
> Project release []: 0.1.0
> Project language [en]: zh_CN
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]:
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
> coverage: checks for documentation coverage (y/n) [n]:
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:

Инициализация завершена, просмотрите структуру каталогов следующим образом:

$ tree --dirsfirst
.
├── build
├── source
│   ├── _static
│   ├── _templates
│   ├── conf.py
│   └── index.rst
├── Makefile
└── make.bat

3.3 Изменить конфигурацию темы

Редактировать файл конфигурации документаdocs/source/conf.py. Тема по умолчаниюalabaster(Ссылка на другие встроенные темы Sphinx [6]), измените его наsphinx_rtd_theme.

html_theme = 'sphinx_rtd_theme'

Дополнение: для поддержки уценки добавьтеrecommonmarkРасширить доextensionsВ списке конфигурации:

extensions = [
    'otherextension',
    '...' ,
    'recommonmark',
]

3.4 Генерация html

make html

html генерируется вbuildВ каталоге просмотрите структуру каталогов следующим образом:

$ tree --dirsfirst -L 2 -I doctrees build
build
└── html
    ├── _sources
    ├── _static
    ├── genindex.html
    ├── index.html
    ├── objects.inv
    ├── search.html
    └── searchindex.js

Локальный предварительный просмотр:

open build/html/index.html

4. Отправьте проект и отправьте на github

cd ..
git add docs
git commit -m "add docs."
git push origin docs:docs

5. Опубликуйте, чтобы прочитать документы

5.1 Разрешение на импорт проектов

Браузер открывает веб-сайт «Читать документы».readthedocs.org. Войдите с авторизацией учетной записи GitHub. «Читать документы» автоматически синхронизирует все проекты GitHub и отображает их в списке, выберите проектimgkernel, нажмите кнопку ➕ справа, чтобы импортировать проект.

5.2 Изменить конфигурацию проекта

Заходим на страницу проекта - управление - дополнительные настройки.

  • Выберите [Ветвь по умолчанию] какdocs
  • Измените [Файл конфигурации Python] наdocs/source/conf.py

Нажмите кнопку [Сохранить] внизу, чтобы сохранить изменения. «Читать документы» повторно потянет веткуdocs, сборка генерирует html . Сборка занимает немного времени.После завершения сборки нажмите зеленую кнопку в правой части главной страницы страницы [Читать документацию], чтобы открыть финальную онлайн-страницу, которая нам нужна.адрес документа.

Его нужно настроить только один раз, и каждый раз, когда вы отправляете документ вdocsBranches, веб-сайт "Read the Docs" автоматически создаст и выпустит, не правда ли, это очень удобно. ^^

6. Документация

Sphinx использует reStructuredText как язык разметки обычного текста по умолчанию. reStructuredText использует справочник по синтаксисуНачало работы с reStructuredText.

Ссылаться на


Отсканируйте QR-код в WeChat, чтобы получить оригиналы новейших технологий

Категории