마크다운 텍스트와 재구성된 텍스트 모두에서 동일한 README 사용

마크다운 텍스트와 재구성된 텍스트 모두에서 동일한 README 사용

깃허브에서 진행하는 프로젝트가 있습니다.이를 위해 나는 GitHub에서 잘 포맷하기 위해 마크다운 구문을 사용하여 README를 작성했습니다.

제 프로젝트가 파이썬에 있기 때문에 파이파이에도 올릴 계획입니다.PyPi에서 README에 사용되는 구문은 reStructuredText입니다.

저는 대략 같은 내용을 포함하는 두 개의 README를 처리해야 하는 것을 피하고 싶습니다. 그래서 저는 RST(또는 그 반대) 번역기까지 마크다운을 검색했지만 찾을 수 없었습니다.

제가 보는 또 다른 해결책은 마크다운/HTML을 수행한 다음 HTML/RST 번역을 수행하는 것입니다.제가 여기저기서 이것에 대한 자료를 찾았으니 가능할 것 같습니다.

제가 하고 싶은 일에 더 잘 맞는 아이디어가 있으십니까?

저는 "하나의 마크업 형식에서 다른 형식으로 파일을 변환하기 위한 스위치 군용 나이프"인 Pandoc을 추천합니다(페이지 하단의 지원되는 변환 다이어그램을 확인하십시오, 매우 인상적입니다).Pandoc은 구조화된 상태로 마크다운할 수 있습니다.텍스트 번역을 직접 수행합니다.사용해 볼 수 있는 온라인 편집기도 있으므로 온라인 편집기를 사용하여 README 파일을 변환할 수 있습니다.

@Chris가 제안한 대로 Pandoc을 사용하여 Markdown을 RST로 변환할 수 있습니다.이것은 파이판독 모듈과 설정의 마법을 사용하여 간단히 자동화될 수 있습니다.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 만 읽습니다.

그래서 당신은 평소처럼 마크다운에 글을 쓸 수 있고 더 이상 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에서 사용하는 Markup 라이브러리는 reStructuredText를 지원합니다.즉, README.rst 파일을 작성할 수 있습니다.

또한 다음을 사용하여 구문별 색상 강조 표시도 지원합니다.code그리고.code-block지시문(예)

PyPI는 이제 긴 설명에 대한 마크다운을 지원합니다!

setup.py, 편집기long_description에 마다운문에, 추가를 합니다.long_description_content_type="text/markdown" 툴링Tooling)을 사용하고 있는지 합니다.setuptools38.6.0+,twine1.11+).

자세한 내용은 더스틴 잉그램의 블로그 게시물을 참조하십시오.

또한 마크다운으로 렌더링되거나 reStructured로 렌더링될 때 문서가 동일한 방식으로 나타나도록 공통 하위 집합으로 작성할 수 있다는 사실에 관심이 있을 수 있습니다.텍스트: https://gist.github.com/dupuy/1855764 ☺

나의 요구 사항으로 나는 컴퓨터에 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

저는 이 문제에 부딪혔고 다음의 bash 스크립트 두 개로 해결했습니다.

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

그게 도움이 되길 바랍니다.

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

언급URL : https://stackoverflow.com/questions/10718767/have-the-same-readme-both-in-markdown-and-restructuredtext