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

212

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

digi604
источник
1
Я не знаю ни одного варианта, доступного для этого. Но обратите внимание, что RST имеет гораздо больше возможностей, чем уценка с точки зрения расширяемости. Поэтому в зависимости от вашего проекта этого может быть недостаточно.
Вольф
2
Существует подмножество rST , которое в основном является действительной уценкой. Если вы ненавидите списки полей Сфинкса (и :param path:т.д.), смотрите расширение Наполеона .
Бени Чернявский-Паскин
3
Если вы хотите задокументировать свой проект Python в Markdown с помощью Sphinx, проголосуйте за запрос функции на bitbucket.org/birkenfeld/sphinx/issue/825/…
полковник Паник,
1
Глядя на этот комментарий, кажется, что вы можете смешать два: read-the-docs.readthedocs.org/en/latest/…
Стефан ван дер Уолт
2
Базовая поддержка Markdown наконец
добралась

Ответы:

97

«Правильный» способ сделать это - написать анализатор 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 поддерживает > ...цитаты), вы получите что-то пригодное для использования, которое поддерживает большинство уценок ,

Бени Чернявский-Паскин
источник
17
Из-за отсутствия прогресса в этой области я могу сделать вывод, что ReST может быть достаточно хорошим и недостаточно отличным, поэтому уценка для такого мероприятия будет того стоить.
Профессор Фалькен
5
TLDR: используйте Recommonmark для написания документации Sphinx с использованием Markdown.
Острокач
предложить добавить новый myst-parserк этому ответу. это победит.
Рик поддерживает Монику
92

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

Marijn
источник
4
Бени упоминает этот подход в своем всеобъемлющем ответе выше . Однако я чувствую, что этот вопрос заслуживает этого простого ответа.
Марин
2
Важно прочитать Recommonmark.readthedocs.org/en/latest/auto_structify.html , особенно, как создать toctree, и как использовать изолированный eval_rstблок для вставки любой конструкции / директивы rST.
Бени Чернявский-Паскин
для этого требуется установить рекоммонмарку и общую марку
XavierCLL
1
Я получаю ImportError: cannot import name 'DocParser'Sphinx 1.4.1 под Python 3.4.3.
детально
2
@detly: ошибка ImportError вызвана последней версией commonmark (0.6.0), нарушающей совместимость с Recommonmark: см. github.com/rtfd/recommonmark/issues/24 . Решение:pip install commonmark==0.5.5 --upgrade
Kadee
30

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

jkmacc
источник
5
MkDocs очень хорошо сработал и здесь для документации конечного пользователя. Все еще пытаюсь использовать уценку внутри строк документации.
Маркус Оттоссон
2
Так много да для этого.
Jkmacc
1
Эй, спасибо - MkDocs - это круто ! Я теряю много энергии и возможностей по сравнению со Sphinx и RST, это точно ... но это невероятно несложно, оптимизировано и так просто и быстро в использовании. Идеально подходит для почти всех моих сценариев использования - таких как краткие инструкции по установке и краткое руководство с некоторыми примерами. В тех немногих случаях, когда мне нужно много объяснений исходного кода - документации по классам и вызовам функций - я придерживаюсь Sphinx.
Брут
На момент написания этого, он поддерживает только 2 уровня отступа TOC.
Вригиэль
@wrygiel Вы не совсем правы - количество отображаемых уровней оглавления зависит от используемой вами темы.
Але
27

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

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

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

pip install commonmark recommonmark

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

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']
Оливер Бествальтер
источник
1
Если получишь cannot import name DocParser, попробуй pip install commonmark==0.5.5.
Роджер Даль
1
Ссылка на документы sphinx должна быть sphinx-doc.org/en/master/usage/markdown.html
Пол Браннан,
21

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

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

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

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

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

bewest
источник
5
«Кажется разумным хотеть сослаться на ваши фрагменты содержания Markdown из вашего проекта sphinx» - это то, что я хочу сделать; Я хочу включить некоторый контент уценки (мой README.md) в мою более полную документацию по Sphinx. Вы знаете, возможно ли это?
детально
8

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

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

the_drow
источник
3
Если я не делаю что-то не так, заменить ReST на Markdown не так просто. Если вы используете такие инструкции, как toctree в исходном файле Markdown, то Pandoc изменит их в одну строку: .. toctree:: :maxdepth: 2 :glob:во время преобразования они перестанут работать. Другими словами, невозможно использовать директивы таким образом.
Виктор Уолк
@WiktorWalc Я не очень знаком с Pandoc, и я на самом деле не пробовал, но, думаю, это имело смысл. Ну что ж. Я попытался. Я думаю, вы можете отправить отчет об ошибке?
the_drow
@WiktorWalc: ..toctreeнедопустимый синтаксис Markdown. Вы либо пишете весь документ в Markdown (и теряете тонкости ReSt), либо используете ReST. Вы не можете иметь свой торт и есть его тоже.
Адитья
1
просто подсказка: решение было бы использовать фильтры pandoc, чтобы пропустить эти специальные инструкции и оставить их как есть при генерации вывода. Я не волшебник фильтров Pandoc, хотя, и это добавляет дополнительную сложность к схеме.
ЗМО
1

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

jkmacc
источник
только начал использовать это, и это фантастика.
Рик поддерживает Монику
0

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