Используя сфинкса со Скидкой с цены вместо RST

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

• Можно схитрить и написать "парсер", который использует Pandoc для преобразования markdown в RST и передает его парсеру RST :-).

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

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

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

UPDATE: https://github.com/sgenoud/remarkdown - это программа для чтения уценки для docutils. Он не использует ни один из вышеперечисленных ярлыков, но использует Parsley PEG грамматику, вдохновленную peg-markdown. Пока не поддерживает директивы.

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

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

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

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

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

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

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

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