2019更新

Question

我在GitHub上托管了一个项目。为此，我使用Markdown语法编写了自述文件，以便在GitHub上很好地格式化。

由于我的项目是Python，我还计划将其上传到PyPi。 PyPi上用于README的语法是reStructuredText。

我希望避免处理包含大致相同内容的两个README;所以我搜索了RST（或其他方式）翻译的降价，但找不到任何。

我看到的另一个解决方案是执行markdown / HTML，然后执行HTML / RST转换。我找到了here和here的一些资源，所以我想它应该是可能的。

你有什么想法可以更好地适应我想做的事情吗？

Answer 1

我会推荐Pandoc，“用于将文件从一种标记格式转换为另一种标记格式的瑞士军刀”（查看页面底部支持的转换图，非常令人印象深刻）。 Pandoc允许直接降格reStructuredText。还有一个在线编辑器here，可以让你试一试，所以你可以简单地使用在线编辑器来转换自述文件。

Answer 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=[]
)

这将使用PyPi自动将README.md转换为RST以获取长描述。当 pypandoc 不可用时，它只是在没有转换的情况下读取README.md - 当他们想要构建模块时不强制其他人安装pypandoc，而不是上传到PyPi。

所以你可以像往常一样写下Markdown而不再关心RST的混乱。 ;）

Answer 3

2019更新

PyPI Warehouse now supports也渲染了Markdown！您只需更新软件包配置并向其添加long_description_content_type='text/markdown'即可。 e.g：

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

因此，无需再将README保持为两种格式。

您可以在documentation。

中找到有关它的更多信息

旧答案：

GitHub使用的Markup库支持reStructuredText。这意味着您可以编写README.rst文件。

他们甚至使用code和code-block指令（Example）支持语法特定的颜色突出显示

Answer 4

PyPI现在支持Markdown进行长描述！

在setup.py中，将long_description设置为Markdown字符串，添加long_description_content_type="text/markdown"并确保您使用的是最近的工具（setuptools 38.6.0 +，{ {1}} 1.11 +）。

有关详细信息，请参阅Dustin Ingram's blog post。

Answer 5

根据我的要求，我不想在我的电脑上安装Pandoc。我用了docverter。 Docverter是一个文档转换服务器，带有一个使用Pandoc的HTTP接口。

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

Answer 6

您可能还会感兴趣的是，可以使用公共子集进行编写，以便在呈现为markdown或呈现为reStructuredText时，文档的显示方式相同：https://gist.github.com/dupuy/1855764☺

Answer 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

我希望有帮助

Answer 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))

在Markdown和reStructuredText中都有相同的自述文件

8 个答案:

2019更新

旧答案：