在Markdown和reStructuredText中都有相同的README
我有一个在GitHub上托pipe的项目。 为此，我使用Markdown语法编写了自述文件，以便在GitHub上对其进行很好的格式化。
由于我的项目是在Python中，我还计划将其上传到PyPi 。 PyPi上用于README的语法是reStructuredText。
我想避免处理两个包含大致相同内容的README文件; 所以我search了RST（或其他方式）翻译的减价，但找不到任何。
我看到的另一个解决scheme是执行降价/ HTML，然后是HTML / RST翻译。 我在这里和这里发现了一些资源，所以我想这应该是可能的。
你有什么想法可以更好地适应我想做的事情吗？
我会推荐Pandoc这个“瑞士军刀，用于将文件从一种标记格式转换为另一种格式”（查看页面底部支持的转换图，这是相当令人印象深刻的）。 Pandoc允许markdown直接reStructuredText翻译。 这里还有一个在线编辑器，可以让你试用它，所以你可以简单地使用在线编辑器来转换你的自述文件。
正如@Chris所build议的那样，您可以使用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而不进行转换 – 当他们想构build模块时不强制别人安装pypandoc，而不是上传到PyPi。
所以你可以像往常一样写Markdown，不再关心RST混乱了。 ;）
GitHub使用的标记库支持reStructuredText。 这意味着你可以写一个README.rst文件。
他们甚至使用code和code-block指令来支持语法特定的颜色突出显示（ 示例 ）
你可能也会对这样一个事实感兴趣，那就是可以用一个通用的子集来写，这样当你的文档以markdown或者reStructuredText的forms呈现时，你的文档就会以相同的方式出现： https： //gist.github.com/dupuy/1855764
对于我的要求，我不想在我的电脑中安装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
我遇到了这个问题，并用下面的两个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
我希望有帮助
使用其他人build议的pandoc工具，我创build了一个md2rst工具来创build第rst文件。 即使这个解决scheme意味着你有一个md和一个rst它似乎是最不具有侵入性，并允许任何未来的减价支持添加。 我更喜欢改变setup.py ，也许你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))
