Mam projekt hostowany na GitHub. W tym celu napisałem plik README przy użyciu składni Markdown, aby ładnie go sformatować na GitHub.

Ponieważ mój projekt jest w Pythonie, planuję również załadować go do PyPi . Składnia używana w plikach README w PyPi to reStructuredText.

Chciałbym uniknąć konieczności obsługi dwóch plików README zawierających z grubsza tę samą zawartość; więc szukałem przeceny na tłumacza RST (lub odwrotnie), ale nie mogłem znaleźć żadnego.

Innym rozwiązaniem, które widzę, jest wykonanie przeceny / HTML, a następnie tłumaczenie HTML / RST. Znalazłem zasoby do tego tutaj i tutaj, więc myślę, że powinno to być możliwe.

Czy miałbyś pomysł, który lepiej pasowałby do tego, co chcę zrobić?

Polecam Pandoc , ten „nóż szwajcarskiej armii, do konwersji plików z jednego formatu na inny znaczników” (zobacz schemat obsługiwanych konwersji na dole strony, jest imponująca). Pandoc umożliwia bezpośrednie tłumaczenie reStructuredText za pomocą Markdown. Jest tu również edytor online , który pozwala go wypróbować, więc możesz po prostu użyć edytora online do konwersji plików README.

Jak zasugerował @Chris, możesz użyć Pandoc do konwersji Markdown na RST. Można to po prostu zautomatyzować za pomocą modułu pypandoc i trochę magii w 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=[]
)

Spowoduje to automatyczną konwersję pliku README.md do RST dla długiego opisu używanego na PyPi. Gdy pypandoc nie jest dostępny, to czyta README.md bez konwersji - aby nie zmuszać innych do instalowania pypandoc, gdy chcą tylko zbudować moduł, a nie przesyłać do PyPi.

Możesz więc pisać w Markdown jak zwykle i nie przejmować się już bałaganem RST. ;)

Aktualizacja 2019

Magazyn PyPI obsługuje renderowanie Markdown, jak dobrze! Wystarczy zaktualizować konfigurację pakietu i dodać long_description_content_type='text/markdown'do niej plik. na przykład:

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

Dlatego nie ma już potrzeby przechowywania README w dwóch formatach.

Więcej informacji na ten temat znajdziesz w dokumentacji .

Stara odpowiedź:

Plik Markup biblioteka wykorzystywana przez GitHub obsługuje reStructuredText. Oznacza to, że możesz napisać plik README.rst.

Obsługują nawet podświetlanie kolorów specyficzne dla składni przy użyciu dyrektyw codei code-block( przykład )

PyPI obsługuje teraz Markdown dla długich opisów!

W setup.py, ustaw long_descriptionciąg Markdown, dodaj long_description_content_type="text/markdown"i upewnij się, że używasz najnowszych narzędzi ( setuptools38.6.0+,twine 1.11+).

Więcej informacji można znaleźć w poście na blogu Dustina Ingrama .

Ze względu na moje wymagania nie chciałem instalować Pandoc na moim komputerze. Użyłem docvertera. Docverter to serwer konwersji dokumentów z interfejsem HTTP wykorzystujący do tego celu 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

Może Cię również zainteresować fakt, że możliwe jest pisanie we wspólnym podzbiorze, dzięki czemu dokument będzie wyglądał tak samo, gdy jest renderowany jako markdown lub renderowany jako reStructuredText: https://gist.github.com/dupuy/1855764 ☺

Natknąłem się na ten problem i rozwiązałem go za pomocą dwóch następujących skryptów bash.

Zwróć uwagę, że mam dołączony LaTeX do mojego 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

Przydaje się również do konwersji do formatu 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

Mam nadzieję że to pomogło

Korzystając z pandocnarzędzia sugerowanego przez innych stworzyłem md2rstnarzędzie do tworzenia rstplików. Mimo że to rozwiązanie oznacza, że ​​masz zarówno opcję, jak mdi rst, wydawało się, że jest najmniej inwazyjne i pozwoliłoby na dodanie jakiejkolwiek przyszłej obsługi przecen. Wolę to od przeróbek, setup.pya może Ty też:

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