Saya benci RST tapi suka sphinx. Apakah ada cara sphinx membaca markdown alih-alih reStructuredText?
python
markdown
python-sphinx
digi604
sumber
sumber
:param path:
dll), lihat ekstensi Napoleon .Jawaban:
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:
Anda bisa menipu dan menulis "parser" yang menggunakan Pandoc untuk mengonversi markdown ke RST dan meneruskannya ke parser RST :-).
Anda dapat menggunakan markdown-> XML parser yang ada dan mentransformasikan hasilnya (menggunakan XSLT?) Ke skema docutils.
Anda bisa mengambil beberapa parser penurunan nama python yang ada yang memungkinkan Anda mendefinisikan renderer kustom dan membuatnya membangun pohon simpul docutils.
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 .
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 .
```eval_rst
blok berpagar serta singkatan untuk arahanDIRECTIVE_NAME:: ...
.PEMBARUAN : MyST adalah satu lagi pembaca docutins / Sphinx. Berdasarkan markdown-it-py, CommonMark kompatibel.
{ROLE_NAME}`...`
sintaksis generik untuk peran.```{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:
`foo`{.method}
->`foo`:method:
.<span class="method">foo</span>
pendekatan kludgiest dengan hanya memasukkan dokumen internal XML!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. .sumber
myst-parser
ke jawaban ini. itu akan menang.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 editconf.py
: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.
sumber
eval_rst
blok berpagar untuk memasukkan konstruksi / arahan rST.ImportError: cannot import name 'DocParser'
Sphinx 1.4.1 di bawah Python 3.4.3.pip install commonmark==0.5.5 --upgrade
Ini tidak menggunakan Sphinx, tetapi MkDocs akan membangun dokumentasi Anda menggunakan Markdown. Saya juga benci pertama, dan sangat menikmati MkDocs sejauh ini.
sumber
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:
sesuaikan
conf.py
:sumber
cannot import name DocParser
, cobapip install commonmark==0.5.5
.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
toctree
tanpa menduplikasi mereka dalam penurunan harga.sumber
README.md
) dalam dokumentasi Sphinx saya yang lebih komprehensif. Tahukah Anda apakah ini mungkin?Ini sekarang didukung secara resmi: http://www.sphinx-doc.org/en/stable/markdown.html
sumber
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.
sumber
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.
sumber
.. toctree:: :maxdepth: 2 :glob:
selama transformasi dan mereka akan berhenti bekerja. Dengan kata lain, tidak mungkin menggunakan arahan dengan cara ini...toctree
tidak 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.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/
sumber
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
sumber