Sử dụng nhân sư với Markdown thay vì RST

Tôi ghét RST nhưng yêu nhân sư. Có cách nào nhân sư đọc markdown thay vì reSturationuredText không?

Cách "thích hợp" để làm điều đó là viết một trình phân tích cú pháp docutils để đánh dấu. (Cộng với tùy chọn Nhân sư để chọn trình phân tích cú pháp.) Vẻ đẹp của điều này sẽ là hỗ trợ tức thì cho tất cả các định dạng đầu ra của docutils (nhưng bạn có thể không quan tâm đến điều đó, vì hầu hết các công cụ đánh dấu tương tự đã tồn tại). Các cách tiếp cận mà không cần phát triển trình phân tích cú pháp từ đầu:

1. Bạn có thể gian lận và viết một "trình phân tích cú pháp" sử dụng Pandoc để chuyển đổi đánh dấu thành RST và chuyển nó cho trình phân tích cú pháp RST :-).

2. Bạn có thể sử dụng bộ đánh dấu hiện có-> trình phân tích cú pháp XML và chuyển đổi kết quả (sử dụng XSLT?) Thành lược đồ docutils.

3. Bạn có thể lấy một số trình phân tích cú pháp đánh dấu python hiện có cho phép bạn xác định trình kết xuất tùy chỉnh và làm cho nó xây dựng cây nút docutils.

4. Bạn có thể rẽ nhánh trình đọc RST hiện có, trích xuất mọi thứ không liên quan đến đánh dấu và thay đổi các cú pháp khác nhau ( so sánh này có thể giúp ích) ...
   EDIT: Tôi không đề xuất lộ trình này trừ khi bạn chuẩn bị kiểm tra kỹ lưỡng. Markdown đã có quá nhiều phương ngữ khác nhau và điều này có thể sẽ dẫn đến một phương ngữ khác ...

CẬP NHẬT: https://github.com/sgenoud/remarkdown là một trình đọc đánh dấu cho docutils. Nó không sử dụng bất kỳ phím tắt nào ở trên mà sử dụng ngữ pháp Parsley PEG lấy cảm hứng từ đánh dấu chốt .

• Chưa hỗ trợ chỉ thị.

CẬP NHẬT: https://github.com/readthedocs/recommonmark và là một trình đọc docutils khác, vốn được hỗ trợ trên ReadTheDocs. Xuất phát từ nhận xét nhưng sử dụng trình phân tích cú pháp CommonMark-py .

• Nó có thể chuyển đổi các cú pháp Markdown tự nhiên cụ thể nhiều hơn hoặc ít hơn sang các cấu trúc phù hợp, ví dụ như danh sách các liên kết đến một toctree. * Không có cú pháp gốc chung cho các vai trò.
• Hỗ trợ nhúng bất kỳ nội dung rST nào , bao gồm các chỉ thị, với một ```eval_rstkhối có rào chắn cũng như một tốc ký cho các chỉ thị DIRECTIVE_NAME:: ....

CẬP NHẬT : MyST là một trình đọc docutins / Sphinx khác. Dựa trên markdown-it-py, tương thích CommonMark.

• Có một {ROLE_NAME}`...`cú pháp chung cho các vai trò.
• Có một cú pháp chung cho các lệnh với ```{DIRECTIVE_NAME} ...các khối có rào chắn.

Trong mọi trường hợp, bạn sẽ cần phát minh ra các phần mở rộng của Markdown để thể hiện các chỉ thị và vai trò của Nhân sư . Trong khi bạn có thể không cần tất cả chúng, một số thích .. toctree::là cần thiết.
Điều này tôi nghĩ là phần khó nhất. tái cấu trúc trước khi các phần mở rộng Sphinx đã phong phú hơn markdown. Ngay cả việc đánh dấu mở rộng rất nhiều, chẳng hạn như pandoc , chủ yếu là một tập hợp con của bộ tính năng rST. Đó là rất nhiều nền tảng để trang trải!

Thực hiện khôn ngoan, điều dễ nhất là thêm một cấu trúc chung để thể hiện bất kỳ vai trò / chỉ thị docutils nào. Các ứng cử viên rõ ràng cho cảm hứng cú pháp là:

• Cú pháp thuộc tính, mà pandoc và một số triển khai khác đã cho phép trên nhiều cấu trúc nội tuyến và khối. Ví dụ `foo`{.method}-> `foo`:method:.
• HTML / XML. Từ <span class="method">foo</span>cách tiếp cận đơn giản nhất chỉ cần chèn docutils XML bên trong!
• Một số loại YAML cho chỉ thị?

Nhưng một ánh xạ chung như vậy sẽ không phải là giải pháp đánh dấu nhiều nhất ... Hiện tại các địa điểm tích cực nhất để thảo luận về tiện ích mở rộng đánh dấu là https://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/

Điều này cũng có nghĩa là bạn không thể sử dụng lại trình phân tích cú pháp đánh dấu mà không mở rộng bằng cách nào đó. Pandoc một lần nữa sống với danh tiếng của mình như một con dao chuyển đổi tài liệu của quân đội Thụy Sĩ bằng cách hỗ trợ các tệp tùy chỉnh . (Trên thực tế, nếu tôi tiếp cận điều này, tôi sẽ cố gắng xây dựng một cầu nối chung giữa người đọc / người biến đổi / nhà văn và người đọc / bộ lọc / nhà văn pandoc. Nó nhiều hơn bạn cần nhưng mức chi trả sẽ rộng hơn nhiều so với chỉ nhân sư / đánh dấu.)

Ý tưởng điên rồ khác: thay vì mở rộng markdown để xử lý Sphinx, hãy mở rộng reSturationuredText để hỗ trợ (chủ yếu) một superset của markdown! Vẻ đẹp là bạn sẽ có thể sử dụng bất kỳ tính năng Nhân sư nào, nhưng vẫn có thể viết hầu hết nội dung trong phần đánh dấu.

Đã có sự chồng chéo cú pháp đáng kể ; cú pháp liên kết đáng chú ý nhất là không tương thích. Tôi nghĩ rằng nếu bạn thêm hỗ trợ cho RST cho các liên kết đánh dấu và ###các tiêu đề kiểu, và thay đổi `backticks`vai trò mặc định thành chữ và có thể thay đổi các khối thụt thành nghĩa đen (RST hỗ trợ > ...cho trích dẫn ngày nay), bạn sẽ nhận được thứ gì đó có thể sử dụng được .

Bạn có thể sử dụng Markdown và reSturationuredText trong cùng một dự án Sphinx. Cách thực hiện việc này được ghi lại ngắn gọn trên Read The Docs .

Cài đặt recommonmark ( pip install recommonmark) và sau đó chỉnh sửa conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

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

Tôi đã tạo một dự án ví dụ nhỏ trên Github (serra / sphinx-with-markdown) để chứng minh cách thức (và điều đó) hoạt động. Nó sử dụng CommonMark 0.5.4 và recommonmark 0.4.0.

Điều này không sử dụng Sphinx, nhưng MkDocs sẽ xây dựng tài liệu của bạn bằng Markdown. Tôi cũng ghét rst, và đã thực sự thích MkDocs cho đến nay.

Cập nhật: điều này hiện được hỗ trợ chính thức và được ghi lại trong các tài liệu nhân sư .

Có vẻ như một triển khai cơ bản đã được đưa vào Sphinx nhưng từ này vẫn chưa được thực hiện. Xem bình luận vấn đề github

cài đặt phụ thuộc:

pip install commonmark recommonmark

điều chỉnh conf.py:

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

Markdown và ReST làm những việc khác nhau.

RST cung cấp một mô hình đối tượng để làm việc với các tài liệu.

Markdown cung cấp một cách để khắc các bit của văn bản.

Có vẻ hợp lý khi muốn tham chiếu các bit nội dung Markdown của bạn từ dự án nhân sư của bạn, sử dụng RST để loại bỏ kiến ​​trúc thông tin tổng thể và luồng của một tài liệu lớn hơn. Hãy để markdown làm những gì nó làm, điều này cho phép các nhà văn tập trung vào viết văn bản.

Có cách nào để tham chiếu một tên miền markdown, chỉ để khắc nội dung như vốn có? RST / nhân sư dường như đã chăm sóc các tính năng như toctreemà không sao chép chúng trong markdown.

Điều này hiện được hỗ trợ chính thức: http://www.sphinx-doc.org/en/urdy/markdown.html

Tôi đã đi với đề nghị của Beni về việc sử dụng pandoc cho nhiệm vụ này. Sau khi cài đặt tập lệnh sau sẽ chuyển đổi tất cả các tệp markdown trong thư mục nguồn thành các tệp đầu tiên, để bạn có thể viết tất cả tài liệu của mình vào markdown. Hy vọng điều này là hữu ích cho những người khác.

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

Có một cách giải quyết.
Kịch bản sphinx-quickstart.py tạo Makefile.
Bạn có thể dễ dàng gọi Pandoc từ Makefile mỗi khi bạn muốn tạo tài liệu để chuyển đổi Markdown thành reSturationuredText.

Đây là một lựa chọn mới. MyST bổ sung một số tính năng cho Markdown, cho phép Sphinx xây dựng các tài liệu giống như rst. https://myst-parser.readthedocs.io/en/latest/

Lưu ý rằng tài liệu xây dựng sử dụng hỗ trợ maven và Sphinx + MarkDown được hỗ trợ đầy đủ bằng cách sử dụng plugin maven sau:

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>