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

106

我有一個託管在GitHub上的項目。爲此，我使用Markdown語法編寫了自述文件，以便在GitHub上對其進行很好的格式化。在Markdown和reStructuredText中都有相同的README文件

由於我的項目是Python，我還計劃將其上傳到PyPi。 PyPi上用於README的語法是reStructuredText。

我想避免必須處理包含大致相同內容的兩個README;所以我搜索了RST（或其他方式）翻譯的降價，但找不到任何。

我看到的另一個解決方案是執行降價/ HTML，然後是HTML/RST翻譯。我發現這here和here一些資源，所以我想應該有可能。

你有什麼想法可以更好地適應我想做的事嗎？

來源

2012-05-23 jlengrand

+20

Github會渲染'README.rst'！ – u0b34a0f6ae

這是新的然後:)但很高興知道，我會嘗試！ – jlengrand

如果您希望PyPI支持Markdown中的自述文件，請通過https://bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes –

我會推薦Pandoc，這是一款將文件從一種標記格式轉換爲另一種格式的瑞士軍刀（請查看頁面底部支持的轉換圖，它非常令人印象深刻）。 Pandoc允許markdown直接進行reStructuredText翻譯。還有一個在線編輯器here，它可以讓你試用它，所以你可以簡單地使用在線編輯器來轉換你的自述文件。

來源

2012-05-23 11:53:40 Chris

+41

對功能請求發表評論。神奇的調用是： 'pandoc --from = markdown --to = rst --output = README.rst README.md' –

正如@Chris所建議的，您可以使用Pandoc將Markdown轉換爲RST。

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模塊和setup.py一些神奇的簡單自動化。當pypandoc不可用時，它只是讀取README.md而不進行轉換 - 不強制他人在他們想構建模塊時安裝pypandoc，而不是上傳到PyPi。

所以你可以像往常一樣寫Markdown，不再關心RST混亂了。 ;）

來源

2014-04-24 10:00:08

這並不能真正解決問題，因爲如果用戶沒有安裝pypandoc（它們可能不會），它會拋出一個錯誤，因爲PyPI預計long_description字段爲RST。如果pypandoc不可用，則應將long_description設置爲None或空字符串。 – Cerin

不，只有在將元數據上傳到PyPi時（只做模塊的開發者，而不是用戶），才需要它。當用戶安裝模塊並且沒有安裝pypandoc時，它不會引發任何錯誤。我已經驗證了這個用例。 –

這也可能會引發運行時錯誤。爲了保持安全，我建議在函數中執行'try-except'。 – varepsilon

GitHub使用的Markup庫支持reStructuredText。這意味着您可以編寫一個README.rst文件。

他們甚至支持使用code和code-block指令（Example）

來源

2014-05-20 02:11:48

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

來源

2014-10-10 19:30:25 robmuh

我就遇到了這個問題，並用兩個以下的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

我希望幫助

來源

2014-11-12 02:34:58 Chet

您可能也有興趣的事實，有可能在一個公共子集來寫，這樣你的文件出來時，作爲降價渲染或呈現同樣的方式作爲reStructuredText：https://gist.github.com/dupuy/1855764☺

來源

2015-02-04 17:03:51 Zooko

對於我的要求，我不想在我的電腦中安裝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

來源

2016-05-05 12:03:45

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

回答

相關問題