Один и тот же README в Markdown и reStructuredText

116

У меня есть проект, размещенный на GitHub. Для этого я написал свой README, используя синтаксис Markdown, чтобы он был красиво отформатирован на GitHub.

Поскольку мой проект написан на Python, я также планирую загрузить его в PyPi . Синтаксис, используемый для README в PyPi, - reStructuredText.

Я бы хотел избежать обработки двух README, содержащих примерно одинаковый контент; поэтому я искал переводчик уценки на RST (или наоборот), но не нашел.

Другое решение, которое я вижу, - это выполнить перевод уценки / HTML, а затем перевод HTML / RST. Я нашел некоторые ресурсы для этого здесь и здесь, поэтому я думаю, что это должно быть возможно.

Не могли бы вы представить, что могло бы лучше соответствовать тому, чем я хочу заниматься?

jlengrand
источник
21
Github выполнит рендеринг README.rst!
u0b34a0f6ae 02
Тогда это в новинку :) Но полезно знать, попробую!
jlengrand 02
6
Если вы хотите, чтобы PyPI поддерживал файлы readmes в Markdown, прокомментируйте запрос функции на bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes
Colonel Panic

Ответы:

88

Я бы порекомендовал Pandoc , «швейцарский армейский нож для преобразования файлов из одного формата разметки в другой» (посмотрите диаграмму поддерживаемых преобразований внизу страницы, она впечатляет). Pandoc позволяет использовать markdown для прямого преобразования текста в текст. Существует также онлайн редактор здесь , который позволяет попробовать его, так что вы можете просто использовать онлайн редактор для преобразования файлов README.

Крис
источник
45
Магическое заклинание: pandoc --from=markdown --to=rst --output=README.rst README.md
Джонатан Юнис
47

Как предложил @Chris, вы можете использовать Pandoc для преобразования Markdown в RST. Это можно просто автоматизировать, используя модуль pypandoc и некоторую магию в setup.py:

from setuptools import setup
try:
    from pypandoc import convert
    read_md = lambda f: convert(f, 'rst')
except ImportError:
    print("warning: pypandoc module not found, could not convert Markdown to RST")
    read_md = lambda f: open(f, 'r').read()

setup(
    # name, version, ...
    long_description=read_md('README.md'),
    install_requires=[]
)

Это автоматически преобразует README.md в RST для длинного описания, используемого в PyPi. Когда pypandoc недоступен, он просто читает README.md без преобразования - чтобы не заставлять других устанавливать pypandoc, когда они хотят просто построить модуль, а не загружать в PyPi.

Таким образом, вы можете писать в Markdown как обычно и больше не беспокоиться о беспорядке RST. ;)

Якуб Джирутка
источник
Это на самом деле не решает проблему, поскольку, если у пользователя не установлен pypandoc (чего, скорее всего, не будет), он выдаст ошибку, поскольку PyPI ожидает, что поле long_description будет RST. Если pypandoc недоступен, вы должны установить для long_description значение None или пустую строку.
Cerin
7
Нет, это нужно только при загрузке метаданных в PyPi (что делает только разработчик модуля, а не пользователи). Он не вызывает ошибок, когда пользователь устанавливает модуль и не установлен pypandoc. Я проверил этот вариант использования.
Якуб Джирутка
Это также может вызвать ошибку времени выполнения. На всякий случай рекомендую try-exceptиспользовать функцию.
varepsilon
1
Отлично! Только одно - я получал RuntimeError: Missing format!исключение, пока не изменил лямбду на read_md = lambda f: convert(f, 'rst', 'md'). Причина в том (я предполагаю), что я передал ему строку, а не файл (поэтому без расширения файла).
frnhr
@frnhr Ваше предположение верно. Pandoc может автоматически определять исходный формат по расширению файла, но когда вы вводите ему строку, вы должны явно указать формат.
Jakub Jirutka
30

Обновление 2019

PyPI Warehouse теперь также поддерживает рендеринг Markdown! Вам просто нужно обновить конфигурацию вашего пакета и добавить long_description_content_type='text/markdown'к нему. например:

setup(
    name='an_example_package',
    # other arguments omitted
    long_description=long_description,
    long_description_content_type='text/markdown'
)

Следовательно, больше нет необходимости хранить README в двух форматах.

Вы можете найти больше информации об этом в документации .

Старый ответ:

Библиотека разметки, используемая GitHub, поддерживает reStructuredText. Это означает, что вы можете написать файл README.rst.

Они даже поддерживают синтаксис определенного цвета подсветки , используя codeи code-blockдирективы ( пример )

Сезар Канасса
источник
6

PyPI теперь поддерживает Markdown для длинных описаний!

В setup.py, установите long_descriptionстроку Markdown, добавьте long_description_content_type="text/markdown"и убедитесь, что вы используете новейшие инструменты ( setuptools38.6.0+, twine1.11+).

См. Сообщение в блоге Дастина Инграма для получения более подробной информации.

Петр Викторин
источник
Приятно услышать! Интересно посмотреть, как со временем продвигается сообщество Python, глядя на историю этой проблемы :).
jlengrand
4

По моим требованиям я не хотел устанавливать Pandoc на свой компьютер. Я использовал доквертер. Docverter - это сервер преобразования документов с HTTP-интерфейсом, использующий для этого Pandoc.

import requests
r = requests.post(url='http://c.docverter.com/convert',
                  data={'to':'rst','from':'markdown'},
                  files={'input_files[]':open('README.md','rb')})
if r.ok:
    print r.content
Давид Миро
источник
3

Вас также может заинтересовать тот факт, что можно писать в общем подмножестве, чтобы ваш документ выглядел одинаково при рендеринге как markdown или reStructuredText: https://gist.github.com/dupuy/1855764

Zooko
источник
1

Я столкнулся с этой проблемой и решил ее двумя следующими сценариями bash.

Обратите внимание, что у меня есть LaTeX, включенный в мой Markdown.

#!/usr/bin/env bash

if [ $# -lt 1 ]; then
  echo "$0 file.md"
  exit;
fi

filename=$(basename "$1")
extension="${filename##*.}"
filename="${filename%.*}"

if [ "$extension" = "md" ]; then
  rst=".rst"
  pandoc $1 -o $filename$rst
fi

Его также полезно преобразовать в HTML. md2html:

#!/usr/bin/env bash

if [ $# -lt 1 ]; then
  echo "$0 file.md <style.css>"
  exit;
fi

filename=$(basename "$1")
extension="${filename##*.}"
filename="${filename%.*}"

if [ "$extension" = "md" ]; then
  html=".html"
  if [ -z $2 ]; then
    # if no css
    pandoc -s -S --mathjax --highlight-style pygments $1 -o $filename$html
  else
    pandoc -s -S --mathjax --highlight-style pygments -c $2 $1 -o $filename$html
  fi
fi

Надеюсь, это поможет

Chet
источник
0

Используя pandocинструмент, предложенный другими, я создал md2rstутилиту для создания rstфайлов. Несмотря на то, что это решение означает, что у вас есть как an, так mdи an, rstоно казалось наименее инвазивным и допускало любую добавленную поддержку уценки в будущем. Я предпочитаю его изменять, setup.pyи, возможно, вы тоже:

#!/usr/bin/env python

'''
Recursively and destructively creates a .rst file for all Markdown
files in the target directory and below.

Created to deal with PyPa without changing anything in setup based on
the idea that getting proper Markdown support later is worth waiting
for rather than forcing a pandoc dependency in sample packages and such.

Vote for
(https://bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes)

'''

import sys, os, re

markdown_sufs = ('.md','.markdown','.mkd')
markdown_regx = '\.(md|markdown|mkd)$'

target = '.'
if len(sys.argv) >= 2: target = sys.argv[1]

md_files = []
for root, dirnames, filenames in os.walk(target):
    for name in filenames:
        if name.endswith(markdown_sufs):
            md_files.append(os.path.join(root, name))

for md in md_files:
    bare = re.sub(markdown_regx,'',md)
    cmd='pandoc --from=markdown --to=rst "{}" -o "{}.rst"'
    print(cmd.format(md,bare))
    os.system(cmd.format(md,bare))
robmuh
источник