Використання сфінкса з Markdown замість RST

Я ненавиджу RST, але люблю сфінкса. Чи існує спосіб, як сфінкс читає розмітку замість reStructuredText?

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

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

2. Ви можете використовувати існуючий розміт-> XML-аналізатор і трансформувати результат (використовуючи XSLT?) В схему docutils.

3. Ви можете взяти деякий існуючий аналізатор розмітки python, який дозволяє визначити користувальницький рендер і змусити його будувати дерево вузлів документів.

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

ОНОВЛЕННЯ: https://github.com/sgenoud/remarkdown - це програма для читання відміток для документів. Він не взяв жодного з перерахованих вище ярликів, але використовує граматику PEG петрушки, натхненну позначкою прив'язки .

• Ще не підтримує директиви.

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

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

ОНОВЛЕННЯ : MyST - це ще одна документація / читач сфінксів. На основі розмітки, сумісний із CommonMark.

• Має загальний {ROLE_NAME}`...`синтаксис ролей.
• Має загальний синтаксис для директив із ```{DIRECTIVE_NAME} ...огородженими блоками.

У всіх випадках вам потрібно буде винайти розширення Markdown, щоб представити директиви та ролі Сфінкса . Хоча вам можуть не знадобитися всі вони, деякі подібні .. 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 знову переживає свою репутацію швейцарського армійського ножа перетворення документів, підтримуючи власні фільти . (Насправді, якби я підійшов до цього, я б спробував побудувати загальний міст між читачами / трансформерами / сценаристами та читачами пандоків / фільтрами / сценаристами. Це більше, ніж потрібно, але окупність буде набагато ширшою, ніж просто сфінкс / відмітка.)

Альтернативна божевільна ідея: замість того, щоб розширювати розмітку для обробки Sphinx, розширити reStructuredText для підтримки (в основному) суперсети розмітки! Краса полягає в тому, що ви зможете використовувати будь-які функції Сфінкса як є, але зможете записувати більшу частину вмісту у розмітку.

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

Ви можете використовувати Markdown та reStructuredText в одному проекті Sphinx. Як це зробити коротко задокументовано в програмі Read The Docs .

Встановіть рекомендаційну позначку ( 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 поки що.

Оновлення: це зараз офіційно підтримується і задокументовано у документах сфінкса .

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

встановити залежності:

pip install commonmark recommonmark

коригувати conf.py:

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

Markdown і ReST роблять різні речі.

RST надає об'єктну модель для роботи з документами.

Розмітка надає спосіб гравірування шматочків тексту.

Здається розумним хотіти посилатись на ваші шматочки вмісту Markdown з вашого проекту сфінксів, використовуючи RST, щоб заглушити загальну архітектуру інформації та потік більшого документа. Нехай розмітка робить те, що вона робить, що дозволяє письменникам зосередитись на написанні тексту.

Чи є спосіб посилатися на домен розмітки, просто гравірувати вміст таким, яким він є? RST / сфінкс, здається, піклувався про такі функції, як 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>