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

Question

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

Answer 1

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

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

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

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

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

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

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

---

Во всех случаях вам нужно будет изобрести расширения 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 поддерживает > ... для цитат), вы Вы получите что-то полезное, что поддерживает большинство уценки.

Answer 2

Вы можете использовать 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.

Answer 3

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

Answer 4

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

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

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

pip install commonmark recommonmark

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

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

Answer 5

Уценка и ReST делают разные вещи.

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

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

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

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

Answer 6

Я согласился с предложением Бени использовать 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(' '))

Answer 7

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

Answer 8

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

Answer 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>