Menggunakan sphinx dengan penurunan harga bukannya RST

Saya benci RST tapi suka sphinx. Apakah ada cara sphinx membaca markdown alih-alih reStructuredText?

Cara "tepat" untuk melakukannya adalah dengan menulis parser docutils untuk penurunan harga. (Ditambah opsi Sphinx untuk memilih parser.) Keindahan ini akan menjadi dukungan instan untuk semua format output docutils (tetapi Anda mungkin tidak peduli tentang itu, karena alat penurunan harga yang serupa sudah ada untuk sebagian besar). Cara untuk mendekati itu tanpa mengembangkan parser dari awal:

1. Anda bisa menipu dan menulis "parser" yang menggunakan Pandoc untuk mengonversi markdown ke RST dan meneruskannya ke parser RST :-).

2. Anda dapat menggunakan markdown-> XML parser yang ada dan mentransformasikan hasilnya (menggunakan XSLT?) Ke skema docutils.

3. Anda bisa mengambil beberapa parser penurunan nama python yang ada yang memungkinkan Anda mendefinisikan renderer kustom dan membuatnya membangun pohon simpul docutils.

4. Anda dapat membayar pembaca RST yang ada, merobek semua yang tidak relevan dengan penurunan harga dan mengubah sintaks yang berbeda ( perbandingan ini mungkin membantu) ...
   EDIT: Saya tidak merekomendasikan rute ini kecuali Anda siap untuk mengujinya dengan berat. Penurunan harga sudah memiliki terlalu banyak dialek yang sedikit berbeda dan ini kemungkinan akan menghasilkan ...

UPDATE: https://github.com/sgenoud/remarkdown adalah pembaca penurunan harga untuk dokumen. Itu tidak mengambil salah satu dari cara pintas di atas tetapi menggunakan tata bahasa Parsley PEG yang terinspirasi oleh pasak-markdown .

• Belum mendukung arahan.

UPDATE: https://github.com/readthedocs/recommonmark dan merupakan pembaca docutils lain, yang didukung secara asli di ReadTheDocs. Berasal dari ucapan tetapi menggunakan pengurai CommonMark-py .

• Ia dapat mengonversi sintaks Penurunan harga tertentu lebih atau kurang alami ke struktur yang sesuai, misalnya daftar tautan ke toctree. * Tidak memiliki sintaksis generik asli untuk peran.
• Mendukung embedding setiap konten RST, termasuk arahan, dengan ```eval_rstblok berpagar serta singkatan untuk arahan DIRECTIVE_NAME:: ....

PEMBARUAN : MyST adalah satu lagi pembaca docutins / Sphinx. Berdasarkan markdown-it-py, CommonMark kompatibel.

• Memiliki {ROLE_NAME}`...`sintaksis generik untuk peran.
• Memiliki sintaksis umum untuk arahan dengan ```{DIRECTIVE_NAME} ...blok berpagar.

Dalam semua kasus, Anda harus menemukan ekstensi Markdown untuk mewakili arahan dan peran Sphinx . Meskipun Anda mungkin tidak membutuhkan semuanya, beberapa suka .. toctree::sangat penting.
Ini menurut saya adalah bagian tersulit. reStructuredText sebelum ekstensi Sphinx sudah lebih kaya daripada penurunan harga. Bahkan penurunan harga yang sangat meluas, seperti pandoc , sebagian besar merupakan himpunan bagian dari set fitur rST. Itu banyak alasan untuk dibahas!

Dari segi implementasi, hal yang paling mudah adalah menambahkan konstruk generik untuk mengekspresikan peran / arahan dokumen. Calon yang jelas untuk inspirasi sintaks adalah:

• Sintaks atribut, yang pandoc dan beberapa implementasi lainnya sudah memungkinkan pada banyak konstruksi inline dan blok. Misalnya `foo`{.method}-> `foo`:method:.
• HTML / XML. Dari <span class="method">foo</span>pendekatan kludgiest dengan hanya memasukkan dokumen internal XML!
• Beberapa jenis YAML untuk arahan?

Namun pemetaan generik semacam itu bukan solusi yang paling tepat untuk penurunan harga ... Saat ini tempat paling aktif untuk membahas ekstensi penurunan harga adalah https://groups.google.com/forum/#!topic/pandoc-discuss , https: // github.com/scholmd/scholmd/

Ini juga berarti Anda tidak bisa menggunakan kembali parser penurunan harga tanpa perlu memperpanjangnya. Pandoc lagi memenuhi reputasinya sebagai pisau konversi dokumen swiss tentara dengan mendukung filtes kustom . (Sebenarnya, jika saya mendekati ini, saya akan mencoba membangun jembatan generik antara pembaca / transformer / penulis dokumen dan pembaca pandoc / filter / penulis. Ini lebih dari yang Anda butuhkan tetapi imbalannya akan jauh lebih luas daripada hanya sphinx / penurunan harga.)

Gagasan alternatif gila: alih-alih memperluas penurunan harga untuk menangani Sphinx, perpanjangtexttrtrured untuk mendukung (kebanyakan) superset penurunan harga! Keindahannya adalah Anda akan dapat menggunakan semua fitur Sphinx apa adanya, namun dapat menulis sebagian besar konten dalam penurunan harga.

Sudah ada banyak tumpang tindih sintaksis ; terutama sintaks tautan tidak kompatibel. Saya pikir jika Anda menambahkan dukungan ke RST untuk tautan penurunan harga, dan ###header gaya, dan mengubah `backticks`peran default menjadi literal, dan mungkin mengubah blok berlekuk menjadi literal (RST mendukung > ...kuotasi saat ini), Anda akan mendapatkan sesuatu yang dapat digunakan yang mendukung sebagian besar penurunan harga. .

Anda dapat menggunakan Markdown dan reStructuredText dalam proyek Sphinx yang sama. Cara melakukannya didokumentasikan secara ringkas di Read The Docs .

Instal tanda rekomendasi ( pip install recommonmark) dan kemudian edit conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

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

Saya telah membuat contoh proyek kecil di Github (serra / sphinx-with-markdown) yang menunjukkan bagaimana (dan itu) kerjanya. Menggunakan CommonMark 0.5.4 dan merekomendasikan 0.4.0.

Ini tidak menggunakan Sphinx, tetapi MkDocs akan membangun dokumentasi Anda menggunakan Markdown. Saya juga benci pertama, dan sangat menikmati MkDocs sejauh ini.

Pembaruan: ini sekarang secara resmi didukung dan didokumentasikan dalam dokumen sphinx .

Sepertinya implementasi dasar telah membuat jalan ke Sphinx tetapi kata belum bulat. Lihat komentar masalah github

instal dependensi:

pip install commonmark recommonmark

sesuaikan conf.py:

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

Penurunan harga dan REST melakukan hal yang berbeda.

RST menyediakan model objek untuk bekerja dengan dokumen.

Penurunan harga menyediakan cara untuk mengukir bit teks.

Tampaknya masuk akal jika ingin mereferensikan bit konten Markdown Anda dari proyek sphinx Anda, menggunakan RST untuk mematikan arsitektur informasi keseluruhan dan aliran dokumen yang lebih besar. Biarkan penurunan harga melakukan apa yang dilakukannya, yang memungkinkan penulis untuk fokus pada menulis teks.

Apakah ada cara untuk merujuk domain penurunan harga, hanya untuk mengukir konten apa adanya? RST / sphinx tampaknya telah merawat fitur seperti toctreetanpa menduplikasi mereka dalam penurunan harga.

Ini sekarang didukung secara resmi: http://www.sphinx-doc.org/en/stable/markdown.html

Saya mengikuti saran Beni untuk menggunakan pandoc untuk tugas ini. Setelah diinstal, skrip berikut akan mengonversi semua file penurunan harga di direktori sumber ke file pertama, sehingga Anda bisa menulis semua dokumentasi Anda dalam penurunan harga. Semoga ini bermanfaat bagi orang lain.

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

Ada solusinya.
Skrip sphinx-quickstart.py menghasilkan Makefile.
Anda dapat dengan mudah memohon Pandoc dari Makefile setiap kali Anda ingin membuat dokumentasi untuk mengonversi Markdown ke reStructuredText.

Ini opsi baru. MyST menambahkan beberapa fitur ke Penurunan harga yang memungkinkan Sphinx untuk membangun dokumen seperti yang pertama kali dilakukan. https://myst-parser.readthedocs.io/en/latest/

Perhatikan bahwa membuat dokumentasi menggunakan maven dan dukungan Sphinx + MarkDown tertanam sepenuhnya didukung oleh plugin maven berikut:

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>