Saya memiliki proyek yang dihosting di GitHub. Untuk ini saya telah menulis README saya menggunakan sintaks Markdown agar dapat diformat dengan baik di GitHub.
Karena proyek saya menggunakan Python, saya juga berencana untuk mengunggahnya ke PyPi . Sintaks yang digunakan untuk README di PyPi adalah reStructuredText.
Saya ingin menghindari keharusan menangani dua README yang berisi konten yang kira-kira sama; jadi saya mencari penurunan harga ke penerjemah RST (atau sebaliknya), tetapi tidak dapat menemukannya.
Solusi lain yang saya lihat adalah melakukan penurunan harga / HTML dan kemudian terjemahan HTML / RST. Saya menemukan beberapa sumber untuk ini di sini dan di sini jadi saya rasa itu harus memungkinkan.
Apakah Anda punya ide yang bisa lebih cocok dengan apa yang ingin saya lakukan?
README.rst
!Jawaban:
Saya akan merekomendasikan Pandoc , "pisau swiss-army untuk mengubah file dari satu format markup ke format lain" (lihat diagram konversi yang didukung di bagian bawah halaman, ini cukup mengesankan). Pandoc memungkinkan penurunan harga ke terjemahan reStructuredText secara langsung. Ada juga editor online di sini yang memungkinkan Anda mencobanya, jadi Anda cukup menggunakan editor online untuk mengonversi file README Anda.
sumber
pandoc --from=markdown --to=rst --output=README.rst README.md
Seperti yang disarankan @Chris, Anda dapat menggunakan Pandoc untuk mengubah Penurunan Harga menjadi RST. Ini dapat secara otomatis menggunakan modul pypandoc dan beberapa keajaiban di setup.py:
Ini secara otomatis akan mengubah README.md menjadi RST untuk deskripsi panjang yang digunakan di PyPi. Saat pypandoc tidak tersedia, maka itu hanya membaca README.md tanpa konversi - untuk tidak memaksa orang lain menginstal pypandoc ketika mereka hanya ingin membangun modul, bukan mengunggah ke PyPi.
Jadi Anda bisa menulis dalam penurunan harga seperti biasa dan tidak peduli dengan kekacauan RST lagi. ;)
sumber
try-except
fungsi tersebut.RuntimeError: Missing format!
pengecualian sampai saya mengubah lambda menjadiread_md = lambda f: convert(f, 'rst', 'md')
. Alasannya (saya menebak) bahwa saya memberinya string dan bukan file (jadi tidak ada ekstensi file).Pembaruan 2019
Gudang PyPI sekarang mendukung rendering penurunan harga juga! Anda hanya perlu memperbarui konfigurasi paket Anda dan menambahkannya
long_description_content_type='text/markdown'
. misalnya:Oleh karena itu, README tidak perlu lagi disimpan dalam dua format.
Anda dapat menemukan informasi lebih lanjut tentangnya di dokumentasi .
Jawaban lama:
The Markup perpustakaan yang digunakan oleh GitHub mendukung reStructuredText. Ini berarti Anda dapat menulis file README.rst.
Mereka bahkan mendukung penyorotan warna khusus sintaks menggunakan perintah
code
dancode-block
( Contoh )sumber
PyPI sekarang mendukung penurunan harga untuk deskripsi panjang!
Di
setup.py
, setellong_description
ke string Markdown, tambahkanlong_description_content_type="text/markdown"
dan pastikan Anda menggunakan perkakas terbaru (setuptools
38.6.0+,twine
1.11+).Lihat entri blog Dustin Ingram untuk lebih jelasnya.
sumber
Untuk kebutuhan saya, saya tidak ingin menginstal Pandoc di komputer saya. Saya menggunakan docverter. Docverter adalah server konversi dokumen dengan antarmuka HTTP menggunakan Pandoc untuk ini.
sumber
Anda mungkin juga tertarik dengan fakta bahwa Anda dapat menulis dalam subset umum sehingga dokumen Anda keluar dengan cara yang sama saat dirender sebagai markdown atau dirender sebagai reStructuredText: https://gist.github.com/dupuy/1855764 ☺
sumber
Saya mengalami masalah ini dan menyelesaikannya dengan dua skrip bash berikut.
Perhatikan bahwa saya memiliki LaTeX yang dibundel ke dalam penurunan harga saya.
Ini juga berguna untuk dikonversi ke html. md2html:
saya harap itu membantu
sumber
Dengan menggunakan
pandoc
alat yang disarankan oleh orang lain, saya membuatmd2rst
utilitas untuk membuatrst
file. Meskipun solusi ini berarti Anda memilikimd
dan danrst
itu tampaknya paling tidak invasif dan akan memungkinkan dukungan penurunan harga apa pun di masa mendatang ditambahkan. Saya lebih suka daripada mengubahsetup.py
dan mungkin Anda juga akan:sumber