การใช้สฟิงซ์กับ Markdown แทน RST

ฉันเกลียด RST แต่รักสฟิงซ์ มีวิธีที่สฟิงซ์อ่าน markdown แทนที่จะเป็น reStructuredText หรือไม่?

วิธีที่ "เหมาะสม" ในการทำเช่นนั้นคือการเขียนตัวแยกวิเคราะห์ docutilsสำหรับการทำเครื่องหมาย (รวมถึงตัวเลือกสฟิงซ์เพื่อเลือกตัวแยกวิเคราะห์) ความสวยงามของสิ่งนี้จะรองรับรูปแบบเอาต์พุต docutils ทั้งหมดทันที (แต่คุณอาจไม่สนใจสิ่งนั้น วิธีในการเข้าถึงโดยไม่พัฒนาโปรแกรมแยกวิเคราะห์ตั้งแต่ต้น:

1. คุณสามารถโกงและเขียน "parser" ที่ใช้Pandocเพื่อแปลง markdown เป็น RST และส่งต่อไปยัง RST parser :-)

2. คุณสามารถใช้ markdown-> ตัวแยกวิเคราะห์ XML ที่มีอยู่และแปลงผลลัพธ์ (โดยใช้ XSLT?) เป็น schema docutils

3. คุณสามารถใช้python markdown python ที่มีอยู่ซึ่งให้คุณกำหนด renderer แบบกำหนดเองและทำให้มันสร้าง tree docutils node tree

4. คุณสามารถแยกผู้อ่าน RST ที่มีอยู่แล้วคัดลอกทุกอย่างที่ไม่เกี่ยวข้องกับการทำเครื่องหมายและเปลี่ยนไวยากรณ์ที่แตกต่างกัน ( การเปรียบเทียบนี้อาจช่วยได้) ...
   แก้ไข: ฉันไม่แนะนำเส้นทางนี้เว้นแต่คุณจะเตรียมการทดสอบอย่างหนัก มาร์กดาวน์มีภาษาที่แตกต่างกันอย่างละเอียดมากเกินไปและอาจส่งผลให้เกิดอีกภาษาหนึ่ง ...

อัปเดต: https://github.com/sgenoud/remarkdownเป็นผู้อ่าน markdown สำหรับ docutils มันไม่ได้ใช้ทางลัดใด ๆ ดังกล่าวข้างต้น แต่ใช้ผักชีฝรั่งไวยากรณ์ PEG แรงบันดาลใจจากPEG-markdown

• ยังไม่รองรับคำสั่ง

อัปเดต: https://github.com/readthedocs/recommonmarkและเป็นเครื่องอ่าน docutils อีกเครื่องหนึ่งซึ่งได้รับการสนับสนุนบน ReadTheDocs ได้มาจากการบอกกล่าว แต่ใช้ตัวแยกวิเคราะห์CommonMark-py

• มันสามารถแปลงไวยากรณ์ Markdown ธรรมชาติที่เฉพาะเจาะจงมากขึ้นหรือน้อยลงเป็นโครงสร้างที่เหมาะสมเช่นรายการลิงก์ไปยัง toctree * ไม่มีไวยากรณ์พื้นฐานดั้งเดิมสำหรับบทบาท
• รองรับการฝังตัวใด ๆเนื้อหา RST รวมทั้งสั่งกับ```eval_rstบล็อกไม่พอใจDIRECTIVE_NAME:: ...เช่นเดียวกับชวเลขสั่ง

UPDATE : MySTเป็นอีกหนึ่งโปรแกรมอ่าน docutins / Sphinx อิงจาก markdown-it-py, CommonMark ที่เข้ากันได้

• มี{ROLE_NAME}`...`ไวยากรณ์ทั่วไปสำหรับบทบาท
• มีไวยากรณ์ทั่วไปสำหรับคำสั่งที่มี ```{DIRECTIVE_NAME} ...บล็อกไม่พอใจ

ในทุกกรณีคุณจะต้องคิดค้นขยาย Markdown เพื่อเป็นตัวแทนของคำสั่งสฟิงซ์และบทบาท แม้ว่าคุณอาจไม่ต้องการทั้งหมด แต่บางอย่าง.. toctree::ก็เป็นสิ่งจำเป็น
ฉันคิดว่านี่เป็นส่วนที่ยากที่สุด reStructuredText ก่อนที่ส่วนขยาย Sphinx จะสมบูรณ์ยิ่งขึ้นกว่า markdown แม้แต่ markdown ที่ยืดเยื้อเช่นpandocก็เป็นชุดย่อยของชุดคุณลักษณะ rST นั่นเป็นพื้นดินมากมายที่จะครอบคลุม!

การนำไปปฏิบัติได้อย่างชาญฉลาดสิ่งที่ง่ายที่สุดคือการเพิ่มโครงสร้างทั่วไปเพื่อแสดงบทบาท / คำสั่ง docutils ใด ๆ ผู้สมัครที่เห็นได้ชัดสำหรับแรงบันดาลใจไวยากรณ์คือ:

• ไวยากรณ์ของแอททริบิวซึ่ง pandoc และการใช้งานอื่น ๆ บางอย่างอนุญาตแล้วในโครงสร้างแบบอินไลน์และบล็อกจำนวนมาก ยกตัวอย่างเช่น->`foo`{.method}`foo`:method:
• HTML / XML จาก<span class="method">foo</span>วิธีการ kludgiest เพียงแทรก docutils ภายใน XML!
• YAML บางอย่างสำหรับคำสั่ง?

แต่เช่นการทำแผนที่ทั่วไปจะไม่เป็นวิธีการแก้ปัญหา markdown-ish มากที่สุด ... ปัจจุบันสถานที่ใช้งานมากที่สุดเพื่อหารือเกี่ยวกับส่วนขยาย markdown มีhttps://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/

นอกจากนี้ยังหมายความว่าคุณไม่สามารถใช้ตัวแยกวิเคราะห์มาร์คดาวน์ซ้ำได้โดยไม่ขยายออกไป Pandoc อีกครั้งชีวิตถึงชื่อเสียงเป็นมีดสวิสกองทัพของการแปลงเอกสารโดยการสนับสนุนfiltes ที่กำหนดเอง (อันที่จริงถ้าฉันจะเข้าใกล้สิ่งนี้ฉันจะพยายามสร้างสะพานเชื่อมระหว่างผู้อ่าน docutils / transformers / นักเขียนและผู้อ่าน pandoc / ตัวกรอง / นักเขียนมันมากกว่าที่คุณต้องการ แต่ผลตอบแทนจะกว้างกว่าแค่สฟิงซ์ / markdown.)

แนวคิดทางเลือกที่บ้าคลั่ง: แทนที่จะขยาย markdown เพื่อจัดการ Sphinx ให้ขยาย reStructuredText เพื่อสนับสนุน (ส่วนใหญ่) superset of markdown! ความงามคือคุณจะสามารถใช้คุณสมบัติสฟิงซ์ใด ๆ ได้ตามที่เป็นอยู่ แต่สามารถเขียนเนื้อหาส่วนใหญ่ได้ในมาร์คดาวน์

มีอยู่แล้วทับซ้อนไวยากรณ์มาก ; ไวยากรณ์ลิงก์ที่สะดุดตาที่สุดนั้นเข้ากันไม่ได้ ฉันคิดว่าถ้าคุณเพิ่มการสนับสนุนให้กับ RST สำหรับลิงก์มาร์คดาวน์และ###- ส่วนหัวสไตล์และเปลี่ยน`backticks`บทบาทเริ่มต้นเป็นตัวอักษรและอาจเปลี่ยนบล็อกที่เยื้องเป็นค่าเฉลี่ยตัวอักษร (RST รองรับ> ...การเสนอราคาทุกวันนี้) คุณจะได้รับสิ่งที่สนับสนุน .

คุณสามารถใช้ 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

สิ่งนี้ไม่ได้ใช้สฟิงซ์ แต่MkDocsจะสร้างเอกสารของคุณโดยใช้ Markdown ฉันยังเกลียด rst และมีความสุขกับ MkDocs จริงๆ

UPDATE:ตอนนี้สนับสนุนอย่างเป็นทางการและการบันทึกไว้ในเอกสารสฟิงซ์

ดูเหมือนว่าการใช้งานขั้นพื้นฐานทำให้มันกลายเป็นสฟิงซ์ แต่คำว่ายังไม่ได้รับรอบ ดูความคิดเห็นปัญหา GitHub

ติดตั้งการพึ่งพา:

pip install commonmark recommonmark

ปรับconf.py:

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

Markdown และ ReST ทำสิ่งต่าง ๆ

RST ให้รูปแบบวัตถุสำหรับการทำงานกับเอกสาร

Markdown เป็นวิธีการแกะสลักข้อความขนาดเล็ก

ดูเหมือนว่าสมเหตุสมผลที่จะต้องการอ้างอิงบิตของเนื้อหา Markdown ของคุณจากโครงการสฟิงซ์ของคุณโดยใช้ RST เพื่อแยกสถาปัตยกรรมข้อมูลโดยรวมและการไหลของเอกสารขนาดใหญ่ ให้ markdown ทำในสิ่งที่ทำซึ่งอนุญาตให้ผู้เขียนมุ่งเน้นที่การเขียนข้อความ

มีวิธีในการอ้างอิงโดเมน markdown เพียงเพื่อแกะสลักเนื้อหาตามที่เป็นอยู่หรือไม่ RST / sphinx ดูเหมือนว่าจะได้รับการดูแลคุณสมบัติเช่นtoctreeโดยไม่ต้องทำซ้ำใน markdown

ตอนนี้ได้รับการสนับสนุนอย่างเป็นทางการแล้ว: http://www.sphinx-doc.org/en/stable/markdown.html

ฉันไปกับข้อเสนอแนะของเบนิในการใช้แพนโดกสำหรับงานนี้ เมื่อติดตั้งแล้วสคริปต์ต่อไปนี้จะแปลงไฟล์ markdown ทั้งหมดในไดเรกทอรีต้นทางเป็นไฟล์ rst เพื่อให้คุณสามารถเขียนเอกสารทั้งหมดของคุณใน markdown หวังว่านี่จะเป็นประโยชน์สำหรับคนอื่น ๆ

#!/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
คุณสามารถเรียกใช้ Pandoc ได้อย่างง่ายดายจาก Makefile ทุกครั้งที่คุณต้องการสร้างเอกสารเพื่อแปลง Markdown เป็น reStructuredText

นี่คือตัวเลือกใหม่ MyST เพิ่มคุณสมบัติบางอย่างให้กับ Markdown ที่อนุญาตให้ Sphinx สร้างเอกสารเช่นเดียวกับ rst 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>