Я ненавижу RST, но люблю сфинкса. Есть ли способ, что sphinx читает уценку вместо reStructuredText?
python
markdown
python-sphinx
digi604
источник
источник
:param path:
т.д.), смотрите расширение Наполеона .Ответы:
«Правильный» способ сделать это - написать анализатор documenttils для уценки. (Плюс опция Sphinx для выбора парсера.) Красота этого заключается в мгновенной поддержке всех форматов вывода documenttils (но вы можете не заботиться об этом, так как подобные инструменты уценки уже существуют для большинства). Способы подойти к этому без разработки парсера с нуля:
Вы можете обмануть и написать «парсер», который использует Pandoc для преобразования уценки в RST и передачи его парсеру RST :-).
Вы можете использовать существующий анализатор markdown-> XML и преобразовать результат (используя XSLT?) В схему Docutils.
Вы могли бы взять какой-нибудь существующий синтаксический анализатор разметки Python, который позволяет вам определить пользовательский рендерер и заставить его строить дерево узлов документирования.
Вы можете раскошелиться на существующий RST-ридер, вырвать все, что не имеет отношения к уценке, и изменить разные синтаксисы ( это сравнение может помочь) ...
РЕДАКТИРОВАТЬ: я не рекомендую этот маршрут, если вы не готовы тщательно его протестировать. У Markdown уже слишком много тонко различающихся диалектов, и это, скорее всего, приведет к еще одному-другому ...
ОБНОВЛЕНИЕ: https://github.com/sgenoud/remarkdown является читателем уценки для документов. Это не заняло ни одного из вышеперечисленных ярлыков, но использует грамматику Parsley PEG, вдохновленную peg-markdown .
ОБНОВЛЕНИЕ: https://github.com/readthedocs/recommonmark и еще одно средство чтения документов, изначально поддерживаемое в ReadTheDocs. Получено из замечаний, но использует синтаксический анализатор CommonMark-py .
```eval_rst
блоком, а также сокращением для директивDIRECTIVE_NAME:: ...
.ОБНОВЛЕНИЕ : MyST - еще один читатель docutins / Sphinx. Основанный на markdown-it-py, совместим с CommonMark.
{ROLE_NAME}`...`
синтаксис для ролей.```{DIRECTIVE_NAME} ...
изолированными блоками.Во всех случаях вам нужно будет придумать расширения Markdown для представления директив и ролей Sphinx . Хотя вам может не понадобиться все из них, некоторые из них
.. toctree::
необходимы.Я думаю, что это самая сложная часть. reStructuredText до того, как расширения Sphinx уже были богаче, чем уценка. Даже сильно расширенная уценка, такая как у pandoc , в основном является подмножеством набора функций rST. Это много земли для покрытия!
В плане реализации проще всего добавить общую конструкцию для выражения любой документированной роли / директивы. Очевидные кандидаты для вдохновения синтаксиса:
`foo`{.method}
->`foo`:method:
.<span class="method">foo</span>
простого подхода к вставке документированного внутреннего XML!Но такое общее сопоставление не будет самым лучшим решением для уценки ... В настоящее время наиболее активными местами для обсуждения расширений уценки являются https://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/
Это также означает, что вы не можете просто повторно использовать анализатор уценки, не расширяя его каким-либо образом. Pandoc снова оправдывает свою репутацию швейцарского армейского ножа конвертации документов, поддерживая пользовательские филе . (На самом деле, если бы я подошел к этому, я бы попытался построить общий мост между читателями / преобразователями / авторами документов и читателями / фильтрами / писателями pandoc. Это больше, чем вам нужно, но выигрыш был бы намного шире, чем просто сфинкс / уценки.)
Альтернативная сумасшедшая идея: вместо расширения уценки для обработки Sphinx, расширьте reStructuredText для поддержки (в основном) супернабора уценки! Прелесть в том, что вы сможете использовать любые функции Sphinx как есть, но сможете писать большую часть контента в уценке.
Существует уже значительный синтаксис перекрытия ; в частности, синтаксис ссылок несовместим. Я думаю, что если вы добавите поддержку RST для ссылок на разметку и
###
заголовков -стилей и измените`backticks`
роль по умолчанию на литеральные, и, возможно, замените блоки с отступом на буквальные (в настоящее время RST поддерживает> ...
цитаты), вы получите что-то пригодное для использования, которое поддерживает большинство уценок ,источник
myst-parser
к этому ответу. это победит.Вы можете использовать Markdown и reStructuredText в одном и том же проекте Sphinx. Как это сделать, кратко документировано в Read The Docs .
Установите Recommonmark (
pip install recommonmark
) и затем отредактируйтеconf.py
:Я создал небольшой пример проекта на Github (serra / sphinx-with-markdown), демонстрирующий, как (и что) он работает. Он использует CommonMark 0.5.4 и рекоммонмарку 0.4.0.
источник
eval_rst
блок для вставки любой конструкции / директивы rST.ImportError: cannot import name 'DocParser'
Sphinx 1.4.1 под Python 3.4.3.pip install commonmark==0.5.5 --upgrade
Это не использует Sphinx, но MkDocs создаст вашу документацию, используя Markdown. Я также ненавижу первое, и до сих пор действительно наслаждаюсь MkDocs.
источник
Обновление: теперь это официально поддерживается и документируется в документах sphinx .
Похоже, базовая реализация пробилась в Sphinx, но слово еще не дошло. См. Комментарий к проблеме GitHub
установить зависимости:
настроить
conf.py
:источник
cannot import name DocParser
, попробуйpip install commonmark==0.5.5
.Markdown и ReST делают разные вещи.
RST предоставляет объектную модель для работы с документами.
Уценка предоставляет способ гравировать биты текста.
Кажется разумным хотеть ссылаться на ваши биты контента Markdown из вашего проекта sphinx, используя RST, чтобы заглушить общую информационную архитектуру и поток большого документа. Пусть markdown делает то, что делает, что позволяет авторам сосредоточиться на написании текста.
Есть ли способ ссылаться на домен уценки, просто гравировать контент как есть? RST / sphinx, кажется, позаботился о таких функциях, как
toctree
без дублирования их в уценке.источник
README.md
) в мою более полную документацию по Sphinx. Вы знаете, возможно ли это?Теперь это официально поддерживается: http://www.sphinx-doc.org/en/stable/markdown.html
источник
Я согласился с предложением Бени использовать pandoc для этой задачи. После установки следующий скрипт преобразует все файлы разметки в исходном каталоге в файлы первого уровня, так что вы можете просто написать всю свою документацию в разметке. Надеюсь, что это полезно для других.
источник
Есть обходной путь.
Сценарий sphinx-quickstart.py генерирует Makefile.
Вы можете легко вызывать Pandoc из Makefile каждый раз, когда вы хотите сгенерировать документацию для преобразования Markdown в reStructuredText.
источник
.. toctree:: :maxdepth: 2 :glob:
во время преобразования они перестанут работать. Другими словами, невозможно использовать директивы таким образом...toctree
недопустимый синтаксис Markdown. Вы либо пишете весь документ в Markdown (и теряете тонкости ReSt), либо используете ReST. Вы не можете иметь свой торт и есть его тоже.Вот новый вариант. MyST добавляет в Markdown некоторые функции, которые позволяют Sphinx создавать документы, как это делает rst. https://myst-parser.readthedocs.io/en/latest/
источник
Обратите внимание, что сборка документации с использованием maven и встроенной поддержки Sphinx + MarkDown полностью поддерживается следующим плагином maven:
https://trustin.github.io/sphinx-maven-plugin/index.html
источник