ฉันมีโครงการที่โฮสต์บน GitHub สำหรับสิ่งนี้ฉันได้เขียน README ของฉันโดยใช้ไวยากรณ์ Markdown เพื่อให้มีรูปแบบที่สวยงามบน GitHub

เป็นโครงการของฉันอยู่ในหลามฉันยังวางแผนที่จะอัปโหลดไปยังPyPi ไวยากรณ์ที่ใช้สำหรับ README บน PyPi คือ reStructuredText

ฉันต้องการหลีกเลี่ยงการจัดการ README สองรายการที่มีเนื้อหาประมาณเดียวกัน ดังนั้นฉันจึงค้นหา markdown เป็น RST (หรือวิธีอื่น ๆ ) ตัวแปล แต่ไม่พบเลย

วิธีแก้ปัญหาอื่นที่ฉันเห็นคือการทำ markdown / HTML แล้วแปล HTML / RST ฉันพบแหล่งข้อมูลสำหรับสิ่งนี้ที่นี่และที่นี่ดังนั้นฉันคิดว่ามันน่าจะเป็นไปได้

คุณมีความคิดที่จะเข้ากับสิ่งที่ฉันอยากทำได้ดีกว่านี้ไหม

ฉันอยากจะแนะนำPandocซึ่งเป็น "มีดสวิสสำหรับการแปลงไฟล์จากรูปแบบมาร์กอัปหนึ่งไปเป็นอีกรูปแบบหนึ่ง" (ตรวจสอบไดอะแกรมของการแปลงที่รองรับที่ด้านล่างของหน้าซึ่งค่อนข้างน่าประทับใจ) Pandoc อนุญาตให้ markdown ทำการแปล reStructuredText โดยตรง นอกจากนี้ยังมีโปรแกรมแก้ไขออนไลน์ที่ให้คุณได้ทดลองใช้ดังนั้นคุณสามารถใช้โปรแกรมแก้ไขออนไลน์เพื่อแปลงไฟล์ README ของคุณได้

ตามที่ @Chris แนะนำคุณสามารถใช้ Pandoc เพื่อแปลง Markdown เป็น RST ได้ สิ่งนี้สามารถทำได้โดยอัตโนมัติโดยใช้โมดูลpypandocและเวทมนตร์บางอย่างใน 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=[]
)

สิ่งนี้จะแปลง README.md เป็น RST โดยอัตโนมัติสำหรับคำอธิบายแบบยาวโดยใช้ PyPi เมื่อpypandocไม่พร้อมใช้งานมันจะอ่าน README.md โดยไม่มีการแปลง - เพื่อไม่บังคับให้ผู้อื่นติดตั้ง pypandoc เมื่อต้องการสร้างโมดูลไม่ใช่อัปโหลดไปยัง PyPi

ดังนั้นคุณสามารถเขียนใน Markdown ได้ตามปกติและไม่ต้องสนใจเรื่อง RST อีกต่อไป ;)

อัปเดต 2019

ขณะนี้ PyPI Warehouse รองรับการแสดงผล Markdown เช่นกัน! คุณเพียงแค่ต้องอัปเดตการกำหนดค่าแพ็คเกจของคุณและเพิ่มlong_description_content_type='text/markdown'เข้าไป เช่น:

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

ดังนั้นจึงไม่จำเป็นต้องเก็บ README ไว้ในสองรูปแบบอีกต่อไป

คุณสามารถค้นหาข้อมูลเพิ่มเติมเกี่ยวกับเรื่องนี้ในเอกสาร

คำตอบเก่า:

Markupห้องสมุดใช้โดย GitHub สนับสนุน reStructuredText ซึ่งหมายความว่าคุณสามารถเขียนไฟล์ README.rst

พวกเขายังสนับสนุนการเน้นสีเฉพาะไวยากรณ์โดยใช้codeและcode-blockคำสั่ง ( ตัวอย่าง )

PyPI รองรับ Markdown สำหรับคำอธิบายแบบยาวแล้ว!

ในsetup.pyตั้งค่าlong_descriptionเป็นสตริง Markdown เพิ่มlong_description_content_type="text/markdown"และตรวจสอบให้แน่ใจว่าคุณใช้เครื่องมือล่าสุด ( setuptools38.6.0+, twine1.11+)

ดู บล็อกโพสต์ของ Dustin Ingramสำหรับรายละเอียดเพิ่มเติม

สำหรับความต้องการของฉันฉันไม่ต้องการติดตั้ง Pandoc ในคอมพิวเตอร์ของฉัน ฉันใช้ docverter Docverterเป็นเซิร์ฟเวอร์แปลงเอกสารที่มีอินเตอร์เฟส HTTP โดยใช้ Pandoc สำหรับสิ่งนี้

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

คุณอาจสนใจในความเป็นไปได้ที่จะเขียนเป็นชุดย่อยทั่วไปเพื่อให้เอกสารของคุณออกมาในลักษณะเดียวกันเมื่อแสดงผลเป็น markdown หรือแสดงผลเป็น reStructuredText: https://gist.github.com/dupuy/1855764 ☺

ฉันพบปัญหานี้และแก้ไขด้วย bash script สองตัวต่อไปนี้

โปรดทราบว่าฉันมี LaTeX รวมอยู่ใน Markdown ของฉัน

#!/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

นอกจากนี้ยังมีประโยชน์ในการแปลงเป็น 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

ฉันหวังว่าจะช่วยได้

ฉันใช้pandocเครื่องมือที่แนะนำโดยผู้อื่นฉันสร้างmd2rstยูทิลิตี้เพื่อสร้างrstไฟล์ แม้ว่าโซลูชันนี้จะหมายความว่าคุณมีทั้ง an mdและrstดูเหมือนว่าจะมีการบุกรุกน้อยที่สุดและจะอนุญาตให้มีการเพิ่มการสนับสนุน markdown ในอนาคต ฉันชอบมากกว่าการเปลี่ยนแปลงsetup.pyและบางทีคุณอาจจะทำเช่นกัน:

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