Вывод на печать для документации на основе Sphinx
Я нашел себя в прецеденте, где помимо генерации HTML и PDF из моих Sphinx источников документации я также хотел бы создать Markdown исходные файлы reStructuredText.
Мое предварительное исследование не нашло поддержки ядра или расширения для этого в Sphinx. Помимо ручного использования pandoc или создания нового расширения Sphinx для задачи, существует ли более простое/более интегрированное решение для этого?
Ответы
Ответ 1
Я не нашел ничего, что могло бы взять файлы reStructuredText и преобразовать их в Markdown, кроме Pandoc, поэтому я написал пользовательский сценарий для Docutils (ссылка реализация reStructuredText и то, на что построен Sphinx). Код доступен на GitHub.
Обратите внимание, что это только начальная реализация: он обрабатывает любой документ reStructuredText без ошибок (протестирован против тестового документа standard.txt из исходного репозитория Docutils), но многие из конструкций reStructuredText (например, замены, необработанные директивы и т.д.) являются не поддерживается и поэтому не включается в вывод Markdown. Я надеюсь добавить поддержку ссылок, кодовых блоков, изображений и таблиц: любая помощь в этом более чем приветствуется - просто продолжайте и развивайте код.
Кажется, что для добавления другого формата записи/вывода в Sphinx вам нужно добавить "строитель" с помощью extension.
Ответ 2
Обновление от ноября 18: теперь доступен sphinx-markdown-builder - благодаря @Jam Risser:
Монтаж
pip3 install sphinx-markdown-builder
зависимости
Python 3
использование
Загрузите расширение в конфигурации.
conf.py
extensions = [
'sphinx_markdown_builder'
]
При использовании Recommonmark, убедитесь, что вы явно игнорируете файлы сборки, поскольку они будут конфликтовать с системой.
conf.py
exclude_patterns = [
'build/*'
]
Создание файлов разметки с помощью Makefile
make markdown
Создание файлов разметки с помощью команды sphinx-build
cd docs
sphinx-build -M markdown ./ build
Рекомендации
пс. Устаревший исходный ответ (поскольку теперь доступен sphinx-markdown-builder): Создан запрос функции для прямой поддержки вывода Markdown на сайте проекта Sphinx: https://github.com/sphinx-doc/sphinx/issues/4219 Спасибо всем, кто проголосовал за это запрос GitHub - это имело значение!
Ответ 3
Если вы хотите использовать pandoc, почему бы вам просто не изменить Makefile Sphinx, когда вы запускаете sphinx-quickstart.py в первый раз, чтобы преобразовать reStructuredText в Markdown?
Это самое простое решение, хотя решение Chris должно работать, если вы включите его в Makefile.
