У меня есть проект, размещенный на GitHub. Для этого я написал свой README, используя синтаксис Markdown, чтобы он был красиво отформатирован на GitHub.
Поскольку мой проект написан на Python, я также планирую загрузить его в PyPi . Синтаксис, используемый для README в PyPi, - reStructuredText.
Я бы хотел избежать обработки двух README, содержащих примерно одинаковый контент; поэтому я искал переводчик уценки на RST (или наоборот), но не нашел.
Другое решение, которое я вижу, - это выполнить перевод уценки / HTML, а затем перевод HTML / RST. Я нашел некоторые ресурсы для этого здесь и здесь, поэтому я думаю, что это должно быть возможно.
Не могли бы вы представить, что могло бы лучше соответствовать тому, чем я хочу заниматься?
README.rst
!Ответы:
Я бы порекомендовал Pandoc , «швейцарский армейский нож для преобразования файлов из одного формата разметки в другой» (посмотрите диаграмму поддерживаемых преобразований внизу страницы, она впечатляет). Pandoc позволяет использовать markdown для прямого преобразования текста в текст. Существует также онлайн редактор здесь , который позволяет попробовать его, так что вы можете просто использовать онлайн редактор для преобразования файлов README.
источник
pandoc --from=markdown --to=rst --output=README.rst README.md
Как предложил @Chris, вы можете использовать Pandoc для преобразования Markdown в RST. Это можно просто автоматизировать, используя модуль pypandoc и некоторую магию в setup.py:
Это автоматически преобразует README.md в RST для длинного описания, используемого в PyPi. Когда pypandoc недоступен, он просто читает README.md без преобразования - чтобы не заставлять других устанавливать pypandoc, когда они хотят просто построить модуль, а не загружать в PyPi.
Таким образом, вы можете писать в Markdown как обычно и больше не беспокоиться о беспорядке RST. ;)
источник
try-except
использовать функцию.RuntimeError: Missing format!
исключение, пока не изменил лямбду наread_md = lambda f: convert(f, 'rst', 'md')
. Причина в том (я предполагаю), что я передал ему строку, а не файл (поэтому без расширения файла).Обновление 2019
PyPI Warehouse теперь также поддерживает рендеринг Markdown! Вам просто нужно обновить конфигурацию вашего пакета и добавить
long_description_content_type='text/markdown'
к нему. например:Следовательно, больше нет необходимости хранить README в двух форматах.
Вы можете найти больше информации об этом в документации .
Старый ответ:
Библиотека разметки, используемая GitHub, поддерживает reStructuredText. Это означает, что вы можете написать файл README.rst.
Они даже поддерживают синтаксис определенного цвета подсветки , используя
code
иcode-block
директивы ( пример )источник
PyPI теперь поддерживает Markdown для длинных описаний!
В
setup.py
, установитеlong_description
строку Markdown, добавьтеlong_description_content_type="text/markdown"
и убедитесь, что вы используете новейшие инструменты (setuptools
38.6.0+,twine
1.11+).См. Сообщение в блоге Дастина Инграма для получения более подробной информации.
источник
По моим требованиям я не хотел устанавливать Pandoc на свой компьютер. Я использовал доквертер. Docverter - это сервер преобразования документов с HTTP-интерфейсом, использующий для этого Pandoc.
источник
Вас также может заинтересовать тот факт, что можно писать в общем подмножестве, чтобы ваш документ выглядел одинаково при рендеринге как markdown или reStructuredText: https://gist.github.com/dupuy/1855764 ☺
источник
Я столкнулся с этой проблемой и решил ее двумя следующими сценариями bash.
Обратите внимание, что у меня есть LaTeX, включенный в мой Markdown.
Его также полезно преобразовать в HTML. md2html:
Надеюсь, это поможет
источник
Используя
pandoc
инструмент, предложенный другими, я создалmd2rst
утилиту для созданияrst
файлов. Несмотря на то, что это решение означает, что у вас есть как an, такmd
и an,rst
оно казалось наименее инвазивным и допускало любую добавленную поддержку уценки в будущем. Я предпочитаю его изменять,setup.py
и, возможно, вы тоже:источник