GitHub에서 호스팅되는 프로젝트가 있습니다. 이를 위해 GitHub에서 멋지게 형식화하기 위해 Markdown 구문을 사용하여 README를 작성했습니다.

내 프로젝트가 Python에 있으므로 PyPi 에도 업로드 할 계획 입니다. PyPi의 README에 사용되는 구문은 reStructuredText입니다.

거의 동일한 내용이 포함 된 두 개의 README를 처리 할 필요가 없습니다. 그래서 RST (또는 그 반대) 번역기에 대한 마크 다운을 검색했지만 찾을 수 없었습니다.

내가 보는 다른 해결책은 마크 다운 / HTML을 수행 한 다음 HTML / RST 번역을 수행하는 것입니다. 여기 와 여기 에서 이에 대한 리소스를 찾았 으므로 가능해야한다고 생각합니다.

내가하고 싶은 일에 더 잘 맞는 아이디어가 있으신가요?

"파일을 한 마크 업 형식에서 다른 형식으로 변환하는 스위스 군용 칼"인 Pandoc 을 추천 합니다 (페이지 하단의 지원되는 변환 다이어그램을 확인하세요. 매우 인상적입니다). Pandoc을 사용하면 마크 다운을 통해 reStructuredText 번역을 직접 수행 할 수 있습니다. 여기에 시험해볼 수 있는 온라인 편집기도 있으므로 온라인 편집기를 사용하여 README 파일을 변환 할 수 있습니다.

@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는 그들은 단지 PyPi에 업로드 할 모듈을 구축하고 싶어 할 때 pypandoc를 설치하려면 다른 사람을 강제하지 - 사용할 수 없습니다, 그것은 바로 변환없이 README.md을 읽습니다.

따라서 평소처럼 Markdown으로 작성할 수 있으며 더 이상 RST 엉망에 대해 신경 쓰지 않아도됩니다. ;)

2019 업데이트

PyPI Warehouse는 이제 Markdown 렌더링도 지원합니다 ! 패키지 구성을 업데이트하고 추가하기 만하면 long_description_content_type='text/markdown'됩니다. 예 :

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

따라서 README를 더 이상 두 가지 형식으로 유지할 필요가 없습니다.

문서 에서 이에 대한 자세한 정보를 찾을 수 있습니다 .

이전 답변 :

마크 업 GitHub의에서 사용하는 라이브러리는 reStructuredText을 지원합니다. 이는 README.rst 파일을 작성할 수 있음을 의미합니다.

code및 code-block지시문을 사용하여 구문 별 색상 강조 표시도 지원합니다 ( 예 ).

PyPI는 이제 긴 설명을 위해 Markdown을 지원합니다!

에서 Markdown 문자열로 setup.py설정 long_description하고 long_description_content_type="text/markdown"최신 도구 ( setuptools38.6.0+, twine1.11+)를 추가 하고 사용하고 있는지 확인합니다 .

자세한 내용은 Dustin Ingram의 블로그 게시물 을 참조하십시오.

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

마크 다운으로 렌더링되거나 reStructuredText로 렌더링 될 때 문서가 동일한 방식으로 나오도록 공통 서브 세트로 작성하는 것이 가능하다는 사실에도 관심이있을 수 있습니다. https://gist.github.com/dupuy/1855764 ☺

이 문제가 발생하여 다음 두 개의 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

도움이 되었기를 바랍니다.

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