[python] Markdown과 reStructuredText에 동일한 README가 있습니다.

Program / 글쓴이

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

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