Использование сфинкса с Markdown вместо RST

Я ненавижу RST, но люблю сфинкса. Есть ли способ, что sphinx читает уценку вместо reStructuredText?

«Правильный» способ сделать это - написать анализатор documenttils для уценки. (Плюс опция Sphinx для выбора парсера.) Красота этого заключается в мгновенной поддержке всех форматов вывода documenttils (но вы можете не заботиться об этом, так как подобные инструменты уценки уже существуют для большинства). Способы подойти к этому без разработки парсера с нуля:

1. Вы можете обмануть и написать «парсер», который использует Pandoc для преобразования уценки в RST и передачи его парсеру RST :-).

2. Вы можете использовать существующий анализатор markdown-> XML и преобразовать результат (используя XSLT?) В схему Docutils.

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

4. Вы можете раскошелиться на существующий RST-ридер, вырвать все, что не имеет отношения к уценке, и изменить разные синтаксисы ( это сравнение может помочь) ...
   РЕДАКТИРОВАТЬ: я не рекомендую этот маршрут, если вы не готовы тщательно его протестировать. У Markdown уже слишком много тонко различающихся диалектов, и это, скорее всего, приведет к еще одному-другому ...

ОБНОВЛЕНИЕ: https://github.com/sgenoud/remarkdown является читателем уценки для документов. Это не заняло ни одного из вышеперечисленных ярлыков, но использует грамматику Parsley PEG, вдохновленную peg-markdown .

• Пока не поддерживает директивы.

ОБНОВЛЕНИЕ: https://github.com/readthedocs/recommonmark и еще одно средство чтения документов, изначально поддерживаемое в ReadTheDocs. Получено из замечаний, но использует синтаксический анализатор CommonMark-py .

• Он может преобразовывать конкретные более или менее естественные синтаксисы Markdown в соответствующие структуры, например, список ссылок на toctree. * Не имеет общего нативного синтаксиса для ролей.
• Поддерживает встраивание любого содержимого rST, включая директивы, с изолированным ```eval_rstблоком, а также сокращением для директив DIRECTIVE_NAME:: ....

ОБНОВЛЕНИЕ : MyST - еще один читатель docutins / Sphinx. Основанный на markdown-it-py, совместим с CommonMark.

• Имеет общий {ROLE_NAME}`...`синтаксис для ролей.
• Имеет общий синтаксис для директив с ```{DIRECTIVE_NAME} ...изолированными блоками.

Во всех случаях вам нужно будет придумать расширения Markdown для представления директив и ролей Sphinx . Хотя вам может не понадобиться все из них, некоторые из них .. toctree::необходимы.
Я думаю, что это самая сложная часть. reStructuredText до того, как расширения Sphinx уже были богаче, чем уценка. Даже сильно расширенная уценка, такая как у pandoc , в основном является подмножеством набора функций rST. Это много земли для покрытия!

В плане реализации проще всего добавить общую конструкцию для выражения любой документированной роли / директивы. Очевидные кандидаты для вдохновения синтаксиса:

• Синтаксис атрибутов, который pandoc и некоторые другие реализации уже разрешают для многих встроенных и блочных конструкций. Например `foo`{.method}-> `foo`:method:.
• HTML / XML. От <span class="method">foo</span>простого подхода к вставке документированного внутреннего XML!
• Какой-то YAML для директив?

Но такое общее сопоставление не будет самым лучшим решением для уценки ... В настоящее время наиболее активными местами для обсуждения расширений уценки являются https://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/

Это также означает, что вы не можете просто повторно использовать анализатор уценки, не расширяя его каким-либо образом. Pandoc снова оправдывает свою репутацию швейцарского армейского ножа конвертации документов, поддерживая пользовательские филе . (На самом деле, если бы я подошел к этому, я бы попытался построить общий мост между читателями / преобразователями / авторами документов и читателями / фильтрами / писателями pandoc. Это больше, чем вам нужно, но выигрыш был бы намного шире, чем просто сфинкс / уценки.)

Альтернативная сумасшедшая идея: вместо расширения уценки для обработки Sphinx, расширьте reStructuredText для поддержки (в основном) супернабора уценки! Прелесть в том, что вы сможете использовать любые функции Sphinx как есть, но сможете писать большую часть контента в уценке.

Существует уже значительный синтаксис перекрытия ; в частности, синтаксис ссылок несовместим. Я думаю, что если вы добавите поддержку RST для ссылок на разметку и ###заголовков -стилей и измените `backticks`роль по умолчанию на литеральные, и, возможно, замените блоки с отступом на буквальные (в настоящее время RST поддерживает > ...цитаты), вы получите что-то пригодное для использования, которое поддерживает большинство уценок ,

Вы можете использовать Markdown и reStructuredText в одном и том же проекте Sphinx. Как это сделать, кратко документировано в Read The Docs .

Установите Recommonmark ( pip install recommonmark) и затем отредактируйте conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

Я создал небольшой пример проекта на Github (serra / sphinx-with-markdown), демонстрирующий, как (и что) он работает. Он использует CommonMark 0.5.4 и рекоммонмарку 0.4.0.

Это не использует Sphinx, но MkDocs создаст вашу документацию, используя Markdown. Я также ненавижу первое, и до сих пор действительно наслаждаюсь MkDocs.

Обновление: теперь это официально поддерживается и документируется в документах sphinx .

Похоже, базовая реализация пробилась в Sphinx, но слово еще не дошло. См. Комментарий к проблеме GitHub

установить зависимости:

pip install commonmark recommonmark

настроить conf.py:

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']

Markdown и ReST делают разные вещи.

RST предоставляет объектную модель для работы с документами.

Уценка предоставляет способ гравировать биты текста.

Кажется разумным хотеть ссылаться на ваши биты контента Markdown из вашего проекта sphinx, используя RST, чтобы заглушить общую информационную архитектуру и поток большого документа. Пусть markdown делает то, что делает, что позволяет авторам сосредоточиться на написании текста.

Есть ли способ ссылаться на домен уценки, просто гравировать контент как есть? RST / sphinx, кажется, позаботился о таких функциях, как toctreeбез дублирования их в уценке.

Теперь это официально поддерживается: http://www.sphinx-doc.org/en/stable/markdown.html

Я согласился с предложением Бени использовать pandoc для этой задачи. После установки следующий скрипт преобразует все файлы разметки в исходном каталоге в файлы первого уровня, так что вы можете просто написать всю свою документацию в разметке. Надеюсь, что это полезно для других.

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))

Есть обходной путь.
Сценарий sphinx-quickstart.py генерирует Makefile.
Вы можете легко вызывать Pandoc из Makefile каждый раз, когда вы хотите сгенерировать документацию для преобразования Markdown в reStructuredText.

Вот новый вариант. MyST добавляет в Markdown некоторые функции, которые позволяют Sphinx создавать документы, как это делает rst. https://myst-parser.readthedocs.io/en/latest/

Обратите внимание, что сборка документации с использованием maven и встроенной поддержки Sphinx + MarkDown полностью поддерживается следующим плагином maven:

https://trustin.github.io/sphinx-maven-plugin/index.html

<plugin>
  <groupId>kr.motd.maven</groupId>
  <artifactId>sphinx-maven-plugin</artifactId>
  <version>1.6.1</version>
  <configuration>
    <outputDirectory>${project.build.directory}/docs</outputDirectory>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>