GitHub'da barındırılan bir projem var. Bunun için, GitHub'da güzel bir şekilde biçimlendirilmesi için README'mi Markdown sözdizimini kullanarak yazdım.

Projem Python'da olduğu için onu PyPi'ye de yüklemeyi planlıyorum . PyPi'de README'ler için kullanılan sözdizimi reStructuredText'tir.

Kabaca aynı içeriğe sahip iki BENİOKU'yu işlemekten kaçınmak istiyorum; bu yüzden RST (veya tam tersi) çevirmenine bir fiyat indirimi aradım, ancak bulamadım.

Gördüğüm diğer çözüm ise bir markdown / HTML ve ardından bir HTML / RST çevirisi yapmak. Bunun için burada ve burada bazı kaynaklar buldum, bu yüzden sanırım mümkün olmalı.

Yapmak istediğim şeye daha iyi uyan bir fikrin var mı?

"Dosyaları bir biçimlendirme biçiminden diğerine dönüştürmek için İsviçre çakısı" Pandoc'u tavsiye ederim (sayfanın altındaki desteklenen dönüştürmeler şemasına bakın, oldukça etkileyici). Pandoc, markdown'ın yeniden Yapılandırılmış Metin çevirisine doğrudan izin verir. Ayrıca burada denemenizi sağlayan çevrimiçi bir düzenleyici de vardır , böylece README dosyalarınızı dönüştürmek için çevrimiçi düzenleyiciyi kullanabilirsiniz.

@Chris'in önerdiği gibi, Markdown'u RST'ye dönüştürmek için Pandoc'u kullanabilirsiniz. Bu, pypandoc modülü ve setup.py'de biraz sihir kullanılarak basitçe otomatikleştirilebilir :

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=[]
)

Bu, README.md'yi PyPi'de kullanarak uzun açıklama için otomatik olarak RST'ye dönüştürecektir. Ne zaman pypandoc onlar sadece PyPi yüklenmeyecektir, modül inşa istediğimde pypandoc yüklemek için başkalarını zorlamamak için - mevcut değildir, o zaman sadece dönüştürme olmadan README.md okur.

Böylece Markdown'da her zamanki gibi yazabilir ve artık RST karışıklığını önemsemeyebilirsiniz. ;)

2019 Güncellemesi

PyPI Warehouse artık Markdown'u da destekliyor ! Paket yapılandırmanızı güncellemeniz ve long_description_content_type='text/markdown'ona eklemeniz yeterlidir . Örneğin:

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

Bu nedenle, README'yi artık iki biçimde tutmanıza gerek yoktur.

Bununla ilgili daha fazla bilgiyi belgelerde bulabilirsiniz .

Eski cevap:

İşaretleme GitHub'dan kullandığı kütüphane reStructuredText destekler. Bu, bir README.rst dosyası yazabileceğiniz anlamına gelir.

codeVe code-blockdirektiflerini kullanarak söz dizimine özgü renk vurgulamayı bile desteklerler ( Örnek )

PyPI artık uzun açıklamalar için Markdown'u destekliyor!

İçinde setup.py, long_descriptionbir Markdown dizesine ayarlayın , en long_description_content_type="text/markdown"son araçları ( setuptools38.6.0+, twine1.11+) ekleyin ve kullandığınızdan emin olun .

Daha fazla ayrıntı için Dustin Ingram'ın blog gönderisine bakın.

Gereksinimlerim için bilgisayarıma Pandoc yüklemek istemedim. Docverter kullandım. Docverter , bunun için Pandoc kullanan bir HTTP arayüzüne sahip bir belge dönüştürme sunucusudur.

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

Belgenizin markdown olarak işlendiğinde veya reStructuredText olarak işlendiğinde aynı şekilde çıkması için ortak bir alt kümeye yazmanın mümkün olduğu gerçeğiyle de ilgilenebilirsiniz: https://gist.github.com/dupuy/1855764 ☺

Bu problemle karşılaştım ve aşağıdaki iki bash komut dosyasıyla çözdüm.

LaTeX'in Markdown'uma dahil edildiğini unutmayın.

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

Ayrıca html'ye dönüştürmek için de kullanışlıdır. 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

umarım bu yardımcı olur

pandocBaşkalarının önerdiği aracı kullanarak dosyaları md2rstoluşturmak için bir yardımcı program oluşturdum rst. Hatta bu çözüm aracı olsa ikisi de bir var mdve bir rsto azından invaziv gibi görünüyordu ve markdown desteği eklenir ne olursa olsun gelecek için izin verecek. Değiştirmeye tercih ederim setup.pyve belki sen de yaparsın:

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