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

나는 RST를 싫어하지만 스핑크스를 좋아합니다. 스핑크스가 reStructuredText 대신 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 )로 변경하면 대부분의 마크 다운을 지원하는 유용한 것을 얻을 수 있다고 생각합니다 .

동일한 Sphinx 프로젝트에서 Markdown 및 reStructuredText를 사용할 수 있습니다. 이 작업을 수행하는 방법은 문서 읽기에 간결하게 문서화되어 있습니다.

recommonmark ( pip install recommonmark)를 설치 한 후 다음을 편집하십시오 conf.py.

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

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

나는 Github (serra / sphinx-with-markdown)에서 어떻게 작동하는지 보여주는 작은 예제 프로젝트 를 만들었습니다 . CommonMark 0.5.4 및 recommonmark 0.4.0을 사용합니다.

이것은 Sphinx를 사용하지 않지만 MkDocs 는 Markdown을 사용하여 문서를 작성합니다. 나는 또한 먼저 미워하고, 지금까지 MkDocs를 즐겼습니다.

업데이트 : 이것은 공식적으로 지원되며 스핑크스 문서에 문서화되어 있습니다.

기본 구현이 스핑크스로 들어가는 것처럼 보이지만 단어는 아직 완성되지 않았습니다. github 이슈 코멘트 참조

설치 종속성 :

pip install commonmark recommonmark

조정 conf.py:

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

마크 다운과 ReST는 다른 일을합니다.

RST는 문서 작업을위한 객체 모델을 제공합니다.

마크 다운은 약간의 텍스트를 조각하는 방법을 제공합니다.

RST를 사용하여 전체 정보 아키텍처와 더 큰 문서의 흐름을 없애기 위해 스핑크스 프로젝트에서 Markdown 콘텐츠를 참조하는 것이 합리적입니다. 마크 다운이하는 일을하게하여 글쓰기에 집중할 수있게합니다.

콘텐츠를 그대로 새기려면 마크 다운 도메인을 참조하는 방법이 있습니까? RST / 스핑크스는 toctree마크 다운에서 복제하지 않고 같은 기능을 처리 한 것으로 보입니다 .

이제 공식적으로 지원됩니다 : http://www.sphinx-doc.org/en/stable/markdown.html

이 작업에 pandoc을 사용하겠다는 Beni의 제안과 함께 갔다. 일단 설치되면 다음 스크립트는 소스 디렉토리의 모든 마크 다운 파일을 첫 번째 파일로 변환하므로 모든 문서를 마크 다운으로 작성할 수 있습니다. 이것이 다른 사람들에게 유용하기를 바랍니다.

#!/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(' '))

해결 방법이 있습니다.
sphinx-quickstart.py 스크립트는 Makefile을 생성합니다.
Markdown을 reStructuredText로 변환하기 위해 문서를 생성 할 때마다 Makefile에서 Pandoc을 쉽게 호출 할 수 있습니다.

새로운 옵션이 있습니다. MyST는 Markdown에 몇 가지 기능을 추가하여 Sphinx가 처음처럼 문서를 작성할 수있게합니다. https://myst-parser.readthedocs.io/en/latest/

maven 및 임베디드 Sphinx + MarkDown 지원을 사용하여 문서 작성 은 다음 maven 플러그인을 통해 완벽하게 지원됩니다.

https://trustin.github.io/sphinx-maven-plugin/index.html

<plugin>
  <groupId>kr.motd.maven</groupId>
  <artifactId>sphinx-maven-plugin</artifactId>
  <version>1.6.1</version>
  <configuration>
    <outputDirectory>${project.build.directory}/docs</outputDirectory>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>