Python 在Markdown和StructuredText中具有相同的自述文件

我在GitHub上主持了一个项目。为此，我使用Markdown语法编写了自述文件，以便在GitHub上对其进行良好的格式化

由于我的项目是用Python编写的，所以我还计划将其上载到。PyPi上的自述文件所使用的语法是reStructuredText

我希望避免处理包含大致相同内容的两份自述；因此，我搜索了一个RST（或其他方式）翻译器的降价，但没有找到

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

---

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

我建议使用“瑞士军刀，用于将文件从一种标记格式转换为另一种标记格式”（查看页面底部支持的转换图表，这非常令人印象深刻）。Pandoc允许markdown直接重构文本翻译。还有一个在线编辑器可供您试用，因此您可以简单地使用在线编辑器转换自述文件。

正如@Chris所建议的，您可以使用Pandoc将标记转换为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而不进行转换——当其他人只想构建模块而不想上传到PyPi时，不强迫他们安装pypandoc

所以你可以像往常一样用降价的方式写，而不再关心RST的混乱

2019年更新 PyPI仓库渲染降价！您只需更新软件包配置并向其中添加

long\u description\u content\u type='text/markdown'

。e、 g:

设置(
name='an_示例_包'，
#省略了其他论点
长描述=长描述，
长\u说明\u内容\u type='text/markdown'
)

因此，不再需要以两种格式保存自述文件

您可以在中找到有关它的更多信息

旧答案： GitHub使用的库支持重构文本。这意味着您可以编写README.rst文件

---

它们甚至支持使用

code

和

code-block

指令（）

使用其他人建议的

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

---

我遇到了这个问题，并用下面两个bash脚本解决了它

请注意，我已将乳胶捆绑到降价中

#!/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

#/usr/bin/env bash
如果[$#-lt 1]；然后
echo“$0 file.md”
出口
fi
文件名=$（基本名称“$1”）
extension=“${filename##*.}”
filename=“${filename%.*}”
如果[“$extension”=“md”]；然后
html=“.html”
如果[-z$2]；然后
#如果没有css
pandoc-s-s--mathjax--highlight style pygments$1-o$filename$html
其他的
pandoc-s-s--mathjax--highlight-style-pygments-c$2$1-o$filename$html
fi
fi

---

我希望这对您有所帮助

您可能还对这样一个事实感兴趣，即可以在一个公共子集中编写文档，以便在将文档呈现为markdown或reStructuredText时以相同的方式呈现：☺

根据我的要求，我不想在我的计算机上安装Pandoc。我用过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

---

PyPI现在支持长描述的降价

在

setup.py

中，将

long\u description

设置为标记字符串，添加

long\u description\u content\u type=“text/Markdown”

，并确保使用的是最新工具（

setuptools

38.6.0+，

twine

1.11+）

---

有关更多详细信息，请参阅。

Github将呈现

README.rst

！这是新的：）但很高兴知道，我会试试！如果您希望PyPI支持Markdown中的自述文件，请在神奇的调用处对功能请求进行评论：

pandoc--from=Markdown--to=rst--output=README.rst README.md

这并不能真正解决问题，因为如果用户没有安装pypandoc（他们可能不会安装），它将抛出一个错误，因为PyPI希望长描述字段是RST。如果pypandoc不可用，您应该将long_description设置为None或空字符串。不，只有在将元数据上载到PyPi时才需要它（这仅用于模块的开发人员，而不是用户）。当用户安装模块并且没有安装pypandoc时，它不会抛出任何错误。我已经验证了这个用例。这也可能引发运行时错误。为了安全起见，我建议在函数中执行

try except

。完美！只有一件事-我得到

运行时错误：缺少格式异常，直到我将lambda更改为
read\u md=lambda f:convert（f，'rst'，'md'）
。原因是（我猜）我给它输入了一个字符串而不是一个文件（所以没有文件扩展名）。@frnhr你的猜测是正确的。Pandoc能够从文件扩展名自动检测源格式，但当您向其输入字符串时，必须明确指定格式。很高兴听到这个消息！看看python社区如何在一段时间内取得进展是很有趣的，看看这个问题的历史：）。