Иметь один и тот же README как в Markdown, так и в reStructuredText

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

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

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

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

У тебя есть идеи, которые могли бы лучше соответствовать тому, что я хочу сделать?

 jlengrand02 февр. 2013 г., 23:31
Тогда это ново :) Но приятно знать, я попробую!
 u0b34a0f6ae02 февр. 2013 г., 15:50
Github будет рендеритьREADME.rst!
 Colonel Panic30 мая 2014 г., 11:57
Если вы хотите, чтобы PyPI поддерживал readmes в Markdown, прокомментируйте запрос функции на Bitbucket.org / pypa / PyPI / вопрос / 148 / Поддержка-уценки-для-файлы README

Ответы на вопрос(8)

Вsetup.py, поставилlong_description к строке уценки, добавьтеlong_description_content_type="text/markdown" и убедитесь, что вы используете последние инструменты setuptools 38.6.0+,twine 1.11 +).

Видеть Пост в блоге Дастина Инграма Больше подробностей

 jlengrand17 мая 2018 г., 08:56
Рад слышать! Интересно посмотреть, как со временем в сообществе питонов достигнут прогресс, глядя на историю этой проблемы:).

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

Я использовал доквертер. 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
2019 Обновление

Склад PyPI теперь поддерживает рендеринг уценки, а также! Вам просто нужно обновить конфигурацию пакета и добавить символ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 в двух форматах.

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

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

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

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

Решение Вопроса

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

 Jonathan Eunice20 мар. 2013 г., 22:49
Волшебный призыв:pandoc --from=markdown --to=rst --output=README.rst README.md

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

 Jakub Jirutka14 мая 2014 г., 21:40
Нет, это нужно только при загрузке метаданных в PyPi (что делает только разработчик модуля, а не пользователи). Он не выдает никакой ошибки, когда пользователь устанавливает модуль, и у него не установлен pypandoc. Я проверил этот вариант использования.
 frnhr10 июл. 2015 г., 23:49
Отлично! Только одно - я получалRuntimeError: Missing format! исключение, пока я не изменил лямбда наread_md = lambda f: convert(f, 'rst', 'md'). Причина (я предполагаю), что я передал ей строку, а не файл (поэтому нет расширения файла).
 Jakub Jirutka11 июл. 2015 г., 01:37
@ frnhr Ваше предположение верно. Pandoc может автоматически определять исходный формат по расширению файла, но когда вы передали ему строку, вы должны явно указать формат.
 Cerin14 мая 2014 г., 21:38
Это на самом деле не решает проблему, поскольку, если у пользователя не установлен pypandoc (что, скорее всего, не будет), он выдаст ошибку, так как PyPI ожидает, что поле long_description будет RST. Если pypandoc недоступен, вы должны установить для long_description значение None или пустую строку.
 varepsilon08 июн. 2014 г., 13:21
Это также может вызвать ошибку во время выполнения. Для того, чтобы остаться в безопасности, я рекомендую сделатьtry-except в функции.

птов 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

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

Используяpandoc инструмент, предложенный другими, я создалmd2rst утилита для созданияrst файлы. Хотя это решение означает, что у вас есть обаmd и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))

Ваш ответ на вопрос