Markdown과 reStructuredText에서 동일한 README를 사용하십시오.

Question

GitHub에서 프로젝트를 호스팅하고 있습니다. 이를 위해 GitHub에서 잘 포맷되도록하기 위해 Markdown 구문을 사용하여 README를 작성했습니다.

내 프로젝트가 파이썬이기 때문에 나는 또한 PyPi에 업로드 할 계획이다. PyPi의 README에 사용되는 구문은 reStructuredText입니다.

대략 동일한 내용을 포함하는 두 개의 README를 처리하지 않으려합니다. 그래서 나는 RST (또는 다른 방법으로) 번역자에게 마크 다운을 검색했지만 어떤 것도 찾을 수 없었다.

내가보기에 다른 해결책은 markdown/HTML을 수행 한 다음 HTML/RST 번역을 수행하는 것입니다. 이 here 및 here에 대한 일부 ressources를 발견 했으므로 가능해야합니다.

내가하고 싶은 것과 잘 어울리는 아이디어가 있습니까?

Answer 1

Pandoc "파일을 하나의 마크 업 형식에서 다른 형식으로 변환하기위한 스위스 군용 칼"(페이지 하단의 지원되는 변환 다이어그램을 확인하십시오. 매우 인상적입니다). Pandoc은 reStructuredText 번역을 직접 markdown 할 수 있습니다. 또한 온라인 편집기 here을 사용해 볼 수도 있으므로 온라인 편집기를 사용하여 README 파일을 간단하게 변환 할 수 있습니다.

Answer 2

@Chris가 제안했듯이 Pandoc을 사용하여 Markdown을 RST로 변환 할 수 있습니다. 이것은 자동으로 PyPi에 사용하는 긴 설명 RST하는 README.md 변환됩니다

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

: 이것은 단순히 pypandoc에게 모듈과 setup.py에 마법을 사용하여 자동화 할 수 있습니다. pypandoc을 사용할 수없는 경우 변환없이 README.md를 읽습니다. PyPi에 업로드하지 않고 다른 사람이 모듈을 빌드하고 싶을 때 pypandoc을 설치하지 않도록합니다.

평소와 같이 Markdown에 쓸 수 있으므로 더 이상 RST 처리에 신경 쓰지 않아도됩니다. ;)

Answer 3

GitHub에서 사용하는 Markup 라이브러리는 reStructuredText를 지원합니다. 즉, README.rst 파일을 작성할 수 있습니다.

그들은 심지어 내가 rst 파일을 생성하기 위해 md2rst 유틸리티를 만들어 다른 사람에 의해 제안 된 pandoc 도구를 사용하여 code 및 code-block 지침 (Example)

Answer 4

를 사용하여 구문 특정 색 강조를 지원합니다. 이 솔루션은 md과 rst을 모두 가지고 있음을 의미하지만, 가장 적은 침해를당한 것으로 보이며 향후 markdown 지원이 추가되는 것을 허용합니다. 나는 어쩌면 당신 것뿐만 아니라 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)) 

Answer 5

나는이 문제에 달려 다음 두 bash는 스크립트를 해결했다.

내 Markdown에 LaTeX를 번들로 제공합니다.

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

당신은 또한 당신의 문서가 인하로 렌더링 또는 렌더링 같은 방법을 제공 있도록 공통 부분 집합에 쓸 수 있다는 사실에 관심이있을 수 있습니다 도움이되기를 바랍니다 as as reStructuredText : https://gist.github.com/dupuy/1855764 ☺

Answer 7

내 요구 사항에 맞게 컴퓨터에 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