[python] RST 대신 Markdown과 함께 스핑크스 사용

“적절한”방법 은 마크 다운을위한 docutils 파서 를 작성하는 것 입니다. (구문 분석기를 선택하기위한 스핑크스 옵션.) 이것의 장점은 모든 docutils 출력 형식을 즉시 지원하는 것입니다. 파서를 처음부터 개발하지 않고 접근하는 방법 :

1. Pandoc 을 사용 하여 markdown을 RST로 변환하고 RST 파서에 전달 하는 “파서”를 속이고 쓸 수 있습니다.

2. 기존 마크 다운-> XML 구문 분석기를 사용하고 XSLT를 사용하여 결과를 docutils 스키마로 변환 할 수 있습니다.

3. 당신은 몇 가지 걸릴 수 있습니다 기존의 파이썬 인하 파서 사용자 정의 렌더러를 정의하고 docutils 노드 트리를 구축 할 수 있습니다.

4. 기존 RST 리더를 포크하여 마크 다운과 관련이없는 모든 것을 제거하고 다른 구문을 변경하면됩니다 ( 이 비교 가 도움 이 될 수 있습니다)
   . Markdown은 이미 미묘하게 다른 방언을 너무 많이 가지고 있기 때문에 또 다른 방언이 생길 것입니다 …

업데이트 : https://github.com/sgenoud/remarkdown 은 docutils의 마크 다운 리더입니다. 위의 단축키를 사용하지 않았지만 peg-markdown에서 영감을 얻은 Parsley PEG 문법을 사용합니다 .

• 지시문을 아직 지원 하지 않습니다 .

업데이트 : https://github.com/readthedocs/recommonmark 는 ReadTheDocs에서 기본적으로 지원되는 다른 docutils 리더입니다. 비고에서 파생되었지만 CommonMark-py 파서를 사용합니다 .

• 그것은 변환 할 수 있습니다 toctree 링크의 적절한 구조를 예를 들어 목록에 특정 다소간 자연 마크 다운 문법을. * 역할에 대한 일반적인 기본 구문이 없습니다.
• 내장 지원하는 모든 으로, 지침을 포함하여 첫 번째 컨텐츠를, ```eval_rst울타리 블록 뿐만 아니라 지시를위한 속기 DIRECTIVE_NAME:: ....

업데이트 : MyST 는 또 다른 docutins / Sphinx 리더입니다. markdown-it-py, CommonMark 호환을 기반으로합니다.

• {ROLE_NAME}`...`역할에 대한 일반적인 구문이 있습니다.
• ```{DIRECTIVE_NAME} ...분리 된 블록이있는 지시문에 대한 일반적인 구문이 있습니다.

에서 모든 경우에, 당신은 표현하기 위해 마크 다운의 확장을 발명해야 스핑크스 지침 및 역할 . 당신이 그들 모두를 필요로하지 않을 수도 있지만, 일부 .. toctree::는 필수적입니다.
이것이 가장 어려운 부분이라고 생각합니다. 스핑크스 확장 이전의 reStructuredText는 이미 마크 다운보다 풍부했습니다. pandoc ‘s 와 같이 크게 확장 된 마크 다운조차도 대부분 rST 기능 세트의 하위 세트입니다. 그것은 다룰 근거가 많습니다!

구현 측면에서 가장 쉬운 것은 docutils 역할 / 지시문을 표현하기 위해 일반 구성을 추가하는 것입니다. 구문 영감의 확실한 후보는 다음과 같습니다.

• pandoc 및 기타 구현에서 이미 많은 인라인 및 블록 구성을 허용하는 속성 구문 예를 들어 `foo`{.method}-> `foo`:method:입니다.
• HTML / XML. <span class="method">foo</span>docutils 내부 XML을 삽입하는 가장 친절한 방법 부터 !
• 지시문에 대한 일종의 YAML?

그러나 이러한 일반적인 매핑은 가장 인상적인 해결책은 아닙니다 … 현재 마크 다운 확장에 대해 가장 활발한 활동은 https://groups.google.com/forum/#!topic/pandoc-discuss , https : //입니다. github.com/scholmd/scholmd/

또한 마크 다운 파서를 어떻게 든 확장하지 않고 재사용 할 수는 없습니다. 판독은 다시 맞춤형 문서를 지원함으로써 문서 변환의 스위스 군용 칼로 명성을 얻었습니다 . (실제로 이것에 접근하려면 docutils 리더 / 변압기 / 라이터와 팬독 리더 / 필터 / 라이터 사이에 일반적인 다리를 만들려고합니다. 필요한 것보다 많지만 스핑크스 / 가격 인하.)

대체 미친 아이디어 : 스핑크스를 처리하기 위해 마크 다운을 확장하는 대신 reStructuredText를 확장하여 마크 다운의 슈퍼 세트를 지원하십시오! 아름다움은 스핑크스 기능을 그대로 사용할 수 있지만 대부분의 콘텐츠를 마크 다운으로 작성할 수 있다는 것입니다.

이미 상당한 구문 겹침이 있습니다 . 가장 주목할만한 링크 구문은 호환되지 않습니다. 마크 다운 링크 및 ###스타일 헤더에 대해 RST에 대한 지원을 추가 하고 기본 `backticks`역할을 리터럴로 변경하고 들여 쓰기 된 블록을 리터럴 ( > ...오늘 인용을 지원 하는 RST )로 변경하면 대부분의 마크 다운을 지원하는 유용한 것을 얻을 수 있다고 생각합니다 .

답변

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

pip install commonmark recommonmark

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))