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

Ответ 1

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

• Вы можете обмануть и написать "парсер", который использует Pandoc, чтобы преобразовать уценку в RST и передать это RST парсер: -).

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

• Вы можете взять какой-то существующий анализатор пропусков python, который позволяет вам определить собственный рендерер и сделать его построенным docutils node tree.

• Вы можете развернуть существующий RST-ридер, вырвать все, что не имеет отношения к уценке и изменить разные синтаксисы (это сравнение может помочь)...
  EDIT: Я не рекомендую этот маршрут, если вы не готовы его проверить. У Markdown уже слишком много тонко разных диалектов, и это, вероятно, приведет к еще одному-другому...

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

ОБНОВЛЕНИЕ: https://github.com/rtfd/recommonmark и является еще одним читателем docutils, поддерживаемым на ReadTheDocs. Производится из замечания, но использует анализатор CommonMark-py. Не поддерживает директивы, но может конвертировать более или менее естественные синтаксисы Markdown в соответствующие структуры, например. список ссылок на toctree. Для других нужд ```eval_rst огороженный блок позволяет вставлять любую директиву rST.

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

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

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

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

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

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

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

Ответ 2

Вы можете использовать Markdown и reStructuredText в том же проекте Sphinx. Как это сделать, лаконично документировано на Прочитать Документы. Установите рекомендательный знак (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.

Ответ 3

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

Ответ 4

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

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

Markdown предоставляет способ вырезать биты текста.

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

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

Ответ 5

Похоже, что базовая реализация сделала это в Sphinx, но слово еще не округло. См. комментарий к проблеме github

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

pip install commonmark recommonmark

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

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

Ответ 6

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

#!/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(' '))

Ответ 7

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

Ответ 8

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

Ответ 9

Обратите внимание, что сборка документации с использованием 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>