Menggunakan sphinx dengan penurunan harga bukannya RST


212

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


1
Saya tidak mengetahui opsi apa pun yang tersedia untuk ini. Tetapi perlu dicatat bahwa RST memiliki lebih banyak pilihan daripada penurunan harga dalam hal ekstensibilitas. Jadi tergantung pada proyek Anda, itu mungkin tidak cukup.
Wolph

2
Ada subset dari rST yang sebagian besar adalah penurunan harga yang valid. Jika Anda membenci daftar bidang Sphinx ( :param path:dll), lihat ekstensi Napoleon .
Beni Cherniavsky-Paskin

3
Jika Anda ingin mendokumentasikan proyek Python Anda di Markdown dengan Sphinx, pilih permintaan fitur di bitbucket.org/birkenfeld/sphinx/issue/825/…
Kolonel Panic

1
Melihat komentar ini, sepertinya Anda dapat mencampur keduanya: read-the-docs.readthedocs.org/en/latest/…
Stefan van der Walt

2
Dukungan Penurunan Nilai Dasar akhirnya berhasil
menembus

Jawaban:


97

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. .


17
Saya menyimpulkan dari kurangnya kemajuan di bidang ini, REST mungkin cukup baik dan tidak cukup berbeda sehingga Markdown untuk usaha seperti itu layak dilakukan.
Prof. Falken

5
TLDR: Gunakan tanda rekomendasi untuk menulis dokumentasi Sphinx menggunakan Markdown.
ostrokach

sarankan menambahkan yang baru myst-parserke jawaban ini. itu akan menang.
Rick mendukung Monica

92

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.


4
Beni menyebutkan pendekatan ini dalam jawaban yang sangat komprehensif di atas . Namun, saya merasa pertanyaan ini layak mendapatkan jawaban sederhana ini.
Marijn

2
Penting untuk membaca recommonmark.readthedocs.org/en/latest/auto_structify.html , terutama cara membuat toctree, dan cara menggunakan eval_rstblok berpagar untuk memasukkan konstruksi / arahan rST.
Beni Cherniavsky-Paskin

ini diperlukan untuk menginstal tanda rekomendasi dan commonmark
XavierCLL

1
Saya mendapatkan ImportError: cannot import name 'DocParser'Sphinx 1.4.1 di bawah Python 3.4.3.
detly

2
@detly: ImportError adalah karena versi terbaru dari commonmark (0.6.0) melanggar kompatibilitas dengan rekomendasi : lihat github.com/rtfd/recommonmark/issues/24 . Solusinya:pip install commonmark==0.5.5 --upgrade
kadee

30

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


5
MkDocs telah bekerja sangat baik di sini juga, untuk dokumentasi pengguna akhir. Masih mencari untuk menggunakan penurunan harga di dalam dokumen ..
Marcus Ottosson

2
Sangat ya untuk ini.
jkmacc

1
Hai, terima kasih - MkDocs luar biasa! Saya kehilangan banyak daya dan fitur dibandingkan dengan Sphinx dan RST, itu sudah pasti ... tetapi sangat rumit, efisien dan sangat mudah dan cepat untuk digunakan. Sempurna untuk hampir semua kasus penggunaan saya - seperti instruksi instal singkat dan beberapa tutorial mulai cepat dengan beberapa contoh. Untuk beberapa kasus, di mana saya perlu menjelaskan banyak kode sumber - kelas ig dan dokumentasi panggilan fungsi - saya tetap menggunakan Sphinx.
Brutus

Pada saat penulisan ini, hanya mendukung 2 level indentasi TOC.
wrygiel

@wrygiel Anda tidak benar - jumlah level TOC yang diberikan tergantung pada tema yang Anda gunakan.
Ale

27

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']

1
Jika sudah cannot import name DocParser, coba pip install commonmark==0.5.5.
Roger Dahl


21

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.


5
"Tampaknya masuk akal jika ingin mereferensikan konten Markdown Anda dari proyek sphinx Anda" - ini sebenarnya yang ingin saya lakukan; Saya ingin memasukkan beberapa konten penurunan harga (saya README.md) dalam dokumentasi Sphinx saya yang lebih komprehensif. Tahukah Anda apakah ini mungkin?
detly


8

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(' '))

1

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.


3
Kecuali saya melakukan sesuatu yang salah, tidak mudah untuk mengganti REST dengan Markdown. Jika Anda menggunakan instruksi seperti toctree dalam file sumber Markdown, maka Pandoc akan mengubahnya menjadi satu baris: .. toctree:: :maxdepth: 2 :glob:selama transformasi dan mereka akan berhenti bekerja. Dengan kata lain, tidak mungkin menggunakan arahan dengan cara ini.
Wiktor Walc

@ WiktorWalc Saya tidak terlalu akrab dengan pandoc dan saya belum benar-benar mencobanya tetapi masuk akal saya kira. Baiklah. Saya mencoba. Saya kira Anda dapat mengajukan laporan bug?
the_drow

@WiktorWalc: ..toctreetidak sintaks Markdown tidak valid. Anda bisa menulis seluruh dokumen dalam penurunan harga (dan kehilangan kebaikan ReSt), atau Anda menggunakan ReST. Anda tidak dapat memiliki kue dan memakannya juga.
Aditya

1
hanya sebuah petunjuk: solusinya adalah menggunakan filter pandoc untuk melewati instruksi khusus tersebut dan membiarkannya seperti pada generasi output. Saya bukan penyihir filter pandoc, dan itu menambah kompleksitas ekstra untuk skema.
zmo


0

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>
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.