Miliki README yang sama baik di Markdown dan reStructuredText

116

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?

jlengrand
sumber
21
Github akan merender README.rst!
u0b34a0f6ae
Ini baru kemudian :) Tapi bagus untuk diketahui, saya akan mencoba!
jlengrand
6
Jika Anda ingin PyPI mendukung readmes dalam Markdown, silakan komentari permintaan fitur di bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes
Kolonel Panic

Jawaban:

88

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.

Chris
sumber
45
Doa magisnya adalah: pandoc --from=markdown --to=rst --output=README.rst README.md
Jonathan Eunice
47

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:

from setuptools import setup
try:
    from pypandoc import convert
    read_md = lambda f: convert(f, 'rst')
except ImportError:
    print("warning: pypandoc module not found, could not convert Markdown to RST")
    read_md = lambda f: open(f, 'r').read()

setup(
    # name, version, ...
    long_description=read_md('README.md'),
    install_requires=[]
)

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

Jakub Jirutka
sumber
Ini tidak benar-benar menyelesaikan masalah, karena jika pengguna tidak menginstal pypandoc (yang kemungkinan besar tidak akan mereka lakukan), itu akan menimbulkan kesalahan, karena PyPI mengharapkan bidang long_description menjadi RST. Jika pypandoc tidak tersedia, Anda harus menyetel long_description ke None atau string kosong.
Cerin
7
Tidak, ini hanya diperlukan saat mengunggah metadata ke PyPi (yang hanya melakukan pengembang modul, bukan pengguna). Itu tidak menimbulkan kesalahan apa pun ketika pengguna menginstal modul dan tidak menginstal pypandoc. Saya telah memverifikasi kasus penggunaan ini.
Jakub Jirutka
Ini juga bisa menimbulkan kesalahan runtime. Untuk tetap berada di sisi yang aman saya sarankan untuk melakukan try-exceptfungsi tersebut.
varepsilon
1
Sempurna! Hanya satu hal - saya mendapatkan RuntimeError: Missing format!pengecualian sampai saya mengubah lambda menjadi read_md = lambda f: convert(f, 'rst', 'md'). Alasannya (saya menebak) bahwa saya memberinya string dan bukan file (jadi tidak ada ekstensi file).
frnhr
@frnhr Tebakan Anda benar. Pandoc dapat mendeteksi otomatis format sumber dari ekstensi file, tetapi ketika Anda memberinya string, Anda harus menentukan formatnya secara eksplisit.
Jakub Jirutka
30

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:

setup(
    name='an_example_package',
    # other arguments omitted
    long_description=long_description,
    long_description_content_type='text/markdown'
)

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 codedan code-block( Contoh )

Cesar Canassa
sumber
6

PyPI sekarang mendukung penurunan harga untuk deskripsi panjang!

Di setup.py, setel long_descriptionke string Markdown, tambahkan long_description_content_type="text/markdown"dan pastikan Anda menggunakan perkakas terbaru ( setuptools38.6.0+, twine1.11+).

Lihat entri blog Dustin Ingram untuk lebih jelasnya.

Petr Viktorin
sumber
Senang mendengarnya! Sangat menarik untuk melihat bagaimana kemajuan dibuat dari waktu ke waktu dalam komunitas python melihat sejarah masalah ini :).
jlengrand
4

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.

import requests
r = requests.post(url='http://c.docverter.com/convert',
                  data={'to':'rst','from':'markdown'},
                  files={'input_files[]':open('README.md','rb')})
if r.ok:
    print r.content
David Miró
sumber
3

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

Zooko
sumber
1

Saya mengalami masalah ini dan menyelesaikannya dengan dua skrip bash berikut.

Perhatikan bahwa saya memiliki LaTeX yang dibundel ke dalam penurunan harga saya.

#!/usr/bin/env bash

if [ $# -lt 1 ]; then
  echo "$0 file.md"
  exit;
fi

filename=$(basename "$1")
extension="${filename##*.}"
filename="${filename%.*}"

if [ "$extension" = "md" ]; then
  rst=".rst"
  pandoc $1 -o $filename$rst
fi

Ini juga berguna untuk dikonversi ke html. md2html:

#!/usr/bin/env bash

if [ $# -lt 1 ]; then
  echo "$0 file.md <style.css>"
  exit;
fi

filename=$(basename "$1")
extension="${filename##*.}"
filename="${filename%.*}"

if [ "$extension" = "md" ]; then
  html=".html"
  if [ -z $2 ]; then
    # if no css
    pandoc -s -S --mathjax --highlight-style pygments $1 -o $filename$html
  else
    pandoc -s -S --mathjax --highlight-style pygments -c $2 $1 -o $filename$html
  fi
fi

saya harap itu membantu

Chet
sumber
0

Dengan menggunakan pandocalat yang disarankan oleh orang lain, saya membuat md2rstutilitas untuk membuat rstfile. Meskipun solusi ini berarti Anda memiliki mddan dan rstitu tampaknya paling tidak invasif dan akan memungkinkan dukungan penurunan harga apa pun di masa mendatang ditambahkan. Saya lebih suka daripada mengubah setup.pydan mungkin Anda juga akan:

#!/usr/bin/env python

'''
Recursively and destructively creates a .rst file for all Markdown
files in the target directory and below.

Created to deal with PyPa without changing anything in setup based on
the idea that getting proper Markdown support later is worth waiting
for rather than forcing a pandoc dependency in sample packages and such.

Vote for
(https://bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes)

'''

import sys, os, re

markdown_sufs = ('.md','.markdown','.mkd')
markdown_regx = '\.(md|markdown|mkd)$'

target = '.'
if len(sys.argv) >= 2: target = sys.argv[1]

md_files = []
for root, dirnames, filenames in os.walk(target):
    for name in filenames:
        if name.endswith(markdown_sufs):
            md_files.append(os.path.join(root, name))

for md in md_files:
    bare = re.sub(markdown_regx,'',md)
    cmd='pandoc --from=markdown --to=rst "{}" -o "{}.rst"'
    print(cmd.format(md,bare))
    os.system(cmd.format(md,bare))
robmuh
sumber