Ответ 1

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

Ответ 2

Как предложил @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 mess.;)

Ответ 3

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 (пример)

Ответ 4

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

В setup.py установите long_description для строки Markdown, добавьте long_description_content_type="text/markdown" и убедитесь, что вы используете последние инструменты (setuptools 38.6. 0+, twine 1. 11+).

См. Сообщение в блоге Dustin Ingram для более подробной информации.

Ответ 5

Для моих требований я не хотел устанавливать Pandoc на свой компьютер. Я использовал docverter. 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

Ответ 6

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

Ответ 7

Я столкнулся с этой проблемой и решил ее с помощью двух следующих сценариев 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

Я надеюсь, что это поможет

Ответ 8

Используя инструмент 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))