reST 대신 Markdown과 함께 Sphinx 사용

reST 대신 Markdown과 함께 Sphinx 사용

나는 reST를 싫어하지만 스핑크스를 사랑한다.스핑크스가 reStructuredText 대신 Markdown을 읽을 수 있는 방법이 있나요?

Markdown 및 reStructured를 사용할 수 있습니다.동일한 Sphinx 프로젝트의 텍스트입니다.이 방법은 Sphinx 설명서에 간결하게 설명되어 있습니다.

myst-parser )pip install myst-parser 편집해 주세요.conf.py:

# simply add the extension to your list of extensions
extensions = ['myst_parser']

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

Github(serra/sphinx-with-markdown)에 대한 간단한 예시 프로젝트를 작성했습니다.Sphinx 버전 3.5.4 및 myst-parser 버전 0.14.0을 사용합니다.

실제로 MyST 파서를 사용하면 Sphinx 문서 전체를 Markdown으로 작성할 수 있습니다.디렉티브를 지원하며 conf.py에서 설정을 통해 활성화할 수 있는 몇 가지 확장기능이 있습니다.

MyST 파서를 사용하려면 Sphinx 2.1 이상이 필요합니다.이전 버전의 Sphinx의 경우 Recommonmark를 사용하여 Sphinx에서 Markdown을 사용할 수 있습니다.방법을 알아보려면 이 답변의 이전 버전을 확인하십시오.

"적절한" 방법은 마크다운을 위한 도큐틸스 파서를 작성하는 것입니다.(파서를 선택하기 위한 스핑크스 옵션도 있습니다.)이 방법의 장점은 모든 docutils 출력 포맷을 즉시 지원하는 것입니다(그러나 대부분의 경우 유사한 마크다운툴이 이미 존재하기 때문에 신경 쓰지 않아도 됩니다).처음부터 파서를 개발하지 않고 접근하는 방법:

1. Pandoc을 사용하여 마크다운을 RST로 변환하고 RST 파서 :-)에 전달하는 "파서"를 치팅 및 쓸 수 있습니다.

2. 기존 마크다운->XML 파서를 사용하여 결과를 (XSLT?를 사용하여) docutils 스키마로 변환할 수 있습니다.

3. 커스텀 렌더러를 정의하여 docutils 노드 트리를 빌드할 수 있는 기존 python 마크다운 파서를 사용할 수 있습니다.

4. 기존 RST 리더를 포크하여 마크다운과 무관한 모든 것을 제거하고 다른 구문을 변경할 수 있습니다(이 비교는 도움이 될 수 있습니다).
   편집: 이 루트를 엄격하게 테스트할 준비가 되어 있지 않다면 권장하지 않습니다.마크다운은 이미 미묘하게 다른 사투리를 너무 많이 가지고 있어서 또 다른 사투리가 생길 것 같아요.

업데이트: https://github.com/sgenoud/remarkdown은 도큐틸의 가격 인하 리더입니다.위의 숏컷을 사용하지 않고 Peg-markdown에서 영감을 얻은 Pagsley PEG 문법을 사용합니다.

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

업데이트: https://github.com/readthedocs/recommonmark 。Read The Docs에서 네이티브로 지원되는 또 다른 문서 작성 리더입니다.remarkdown에서 파생되지만 CommonMark-py 파서를 사용합니다.

• 다소 자연스러운 마크다운 구문을 적절한 구조(예: toctree 링크 목록)로 변환할 수 있습니다.* 역할에 대한 일반적인 네이티브 구문이 없습니다.
• 디렉티브를 포함한 모든 rST 콘텐츠를 펜스 블록과 디렉티브의 약자로 삽입할 수 있습니다.DIRECTIVE_NAME:: ....

업데이트: MyST는 또 다른 도큐틴/스핑크스 리더입니다.Markdown-it-py에 따라 Common Mark 호환.

• 인 용 has{ROLE_NAME}`...`구문을 지정합니다.
• 을 사용합니다. ```{DIRECTIVE_NAME} ...울타리가 쳐진 블록

---

모든 경우 스핑크스의 지시와 역할을 나타내기 위해 Markdown의 확장을 개발해야 합니다.모든 것이 필요한 것은 아니지만, 다음과 같은 것도 있습니다... toctree::필수불가결합니다.
이게 제일 어려운 부분인 것 같아요. 재구성된 것 같아요.Sphinx 확장자 이전의 텍스트가 이미 마크다운보다 풍부했습니다.pandoc과 같이 대폭 확장된 마크다운도 대부분 rST 피쳐 세트의 서브셋입니다.가려야 할 게 많네요!

구현 측면에서 가장 쉬운 것은 일반적인 구성을 추가하여 모든 docutils 역할/지시를 표현하는 것입니다.구문 영감을 얻을 수 있는 명백한 후보는 다음과 같습니다.

• 속성 구문: pandoc 및 기타 일부 구현에서 이미 많은 인라인 및 블록 구성을 허용합니다.를 들어, 「」입니다.`foo`{.method}->`foo`:method:.
• /XML 에서.<span class="method">foo</span> 되는 설명하겠습니다.
• 길잡이 YAML 같은 거?

그러나 이러한 일반적인 매핑이 가장 가격 인하와 유사한 솔루션은 아닐 것입니다.현재 마크다운 확장에 대해 논의하는 가장 적극적인 장소는 https://groups.google.com/forum/#!http/http:/http:/http:/https://github.com/scholmd/scholmd/ 입니다.

즉, 마크다운 파서를 확장하지 않고는 재사용할 수 없습니다.판독은 맞춤형 필테를 지원함으로써 문서 변환의 스위스 군용 나이프라는 명성에 걸맞게 살아가고 있다.(실제로 이 방법에 접근한다면, 도큐필 독자/트랜스포머/라이터와 범독 독자/필터/라이터 사이에 일반적인 가교를 구축하려고 합니다.필요 이상의 성과이지만 스핑크스/마크다운보다 훨씬 더 큰 성과를 거둘 수 있습니다.)

---

또 다른 미친 아이디어: 스핑크스를 처리하기 위해 마크다운을 확장하는 대신 reStructured를 확장합니다.(대부분) 마크다운의 슈퍼셋을 지원하는 텍스트!장점은 스핑크스 기능을 그대로 사용할 수 있지만 대부분의 콘텐츠를 마크다운으로 작성할 수 있다는 것입니다.

이미 상당한 구문이 중복되어 있습니다.특히 링크 구문이 호환되지 않습니다.만약 당신이 RST에 마크다운 링크 지원을 받을 수 있을 것 같습니다.###headers 및 default - style " " " " " " 。`backticks`리터럴로 해, 리터럴로 는 리터럴을 지원합니다).> ...가격 인하를 지원하는 유용한 정보를 얻을 수 있습니다.

이것은 스핑크스를 사용하지 않지만 MkDocs는 Markdown을 사용하여 문서를 작성합니다.저도 rst를 싫어하고 지금까지 MkDocs를 정말 즐겼어요.

2021년 5월 갱신: resetonmark는 myst-parser를 위해 폐지됩니다(고맙습니다).

업데이트: 이 기능은 이제 sphinx 문서에 공식적으로 지원 및 문서화되어 있습니다.

기본적인 구현이 스핑크스에 들어온 것 같지만 아직 소문이 퍼지지 않았다.github 문제 설명 참조

설치 의존관계:

pip install commonmark recommonmark

conf.py:

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

Markdown과 ReST는 다른 작업을 수행합니다.

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

마크다운은 텍스트의 일부를 새기는 방법을 제공합니다.

스핑크스 프로젝트에서 마크다운 콘텐츠의 비트를 참조하고 RST를 사용하여 전체적인 정보 아키텍처와 더 큰 문서의 흐름을 배제하는 것이 타당해 보입니다.마크다운은 작가들이 텍스트 쓰기에 집중할 수 있도록 하는 것입니다.

마크다운 도메인을 참조할 수 있는 방법이 있습니까?에서는 RST/스핑크스 등의 기능이 잘 것 .toctree을 사용하다

MyST Markdown 사용을 권장합니다.이것은 reStructuredText의 주요 기능을 가져오도록 설계된 Markdown의 맛입니다.MyST는 Experious Structured Text의 약자로, "RST but with Markdown"이라고 생각할 수 있습니다.

MyST는 CommonMark 표준의 슈퍼셋으로 패키지를 통해 CommonMark에 대한 개별 확장 컬렉션으로 정의됩니다).즉, CommonMark 구문은 MyST에서 즉시 사용할 수 있지만 원하는 경우 더 많은 구문 기능을 사용할 수도 있습니다.

MyST는 reStructuredText의 거의 모든 기능에 대한 구문을 가지고 있으며 동일한 기능을 다시 만들 수 있도록 전체 Sphinx 테스트 스위트에 대해 테스트됩니다.예를 들어 다음과 같습니다.

MyST에서 지시문을 작성하는 방법은 다음과 같습니다.

```{directivename} directive options
:key: value
:key2: value2

Directive content
```

MyST에서 역할을 작성하는 방법은 다음과 같습니다.

Here's some text and a {rolename}`role content`

MyST Markdown용 스핑크스 파서는 Markdown 링크 구문 사용 등 스핑크스 고유의 기능도 갖추고 있습니다.[some text](somelink))는 스핑크스의 상호 참조도 처리합니다.예를 들어 MyST에서 라벨을 정의하고 다음과 같이 참조할 수 있습니다.

(my-label)=
# My header

Some text and a [cross reference](my-label).

MyST Markdown 구문의 보다 완전한 목록은 Jupyter Book cheatsheet입니다.이것에는, 많은 일반적인 문서 요구의 리스트와 그것을 실현하기 위한 각각의 MyST 구문이 포함되어 있습니다(MyST는, 기술적인 관점에서는 완전히 독립형 프로젝트로 존재하지만, Jupyter Book의 컴포넌트로 작성되었습니다).

MyST는 현재 Sphinx 문서 및 Read The Docs 문서에서 Sphinx에 권장되는 Markdown 툴입니다.

MyST 파서를 Sphinx 문서에 추가하려면 다음 절차를 수행하십시오.

pip install myst-parser

그리고...conf.py, 추가:

extensions = [
  ...
  "myst_parser",
  ...
]

이제 Sphinx 문서에서 CommonMark Markdown 구문과 확장 MyST Markdown 구문을 구문 분석할 수 있습니다.자세한 내용은 MyST 문서를 참조하십시오.

이것이 몇 가지 사항을 명확히 하는 데 도움이 되기를 바랍니다!

이는 현재 공식적으로 지원되고 있습니다.http://www.sphinx-doc.org/en/stable/markdown.html

URL 자동 링크를 만들기 위한 linkify 등의 내선 번호에 대해서는, https://myst-parser.readthedocs.io/en/latest/syntax/optional.html 를 참조해 주세요.

저는 이 작업에 판독을 사용하자는 베니의 제안에 동의했습니다.설치 후 다음 스크립트는 소스 디렉토리에 있는 모든 마크다운파일을 rst파일로 변환하여 모든 문서를 마크다운으로 작성할 수 있도록 합니다.이것이 다른 사람들에게 유용하기를 바랍니다.

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

여기 새로운 옵션이 있습니다.MyST는 마크다운에 몇 가지 기능을 추가하여 Sphinx가 rst와 같이 문서를 작성할 수 있도록 합니다.https://myst-parser.readthedocs.io/en/latest/

회피책이 있습니다.
sphinx-quickstart.py 스크립트는 Make 파일을 생성합니다.
Markdown †구조변경Text로 변환하기 위해 문서를 생성할 때마다 Makefile에서 Pandoc을 쉽게 호출할 수 있습니다.

maven 및 Embedded 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>

은 to이에 to to to to의 입니다.recommonmark★★★★★★ 。

pip install recommonmark

개인적으로는 Sphinx 3.5.1을 사용하고 있기 때문에

# for Sphinx-1.4 or newer
extensions = ['recommonmark']

여기 공식 문서를 확인해 보세요.

언급URL : https://stackoverflow.com/questions/2471804/using-sphinx-with-markdown-instead-of-rest