У мене розміщений проект на GitHub. Для цього я написав свою README, використовуючи синтаксис Markdown для того, щоб він добре відформатувався на GitHub.

Оскільки мій проект знаходиться в Python, я також планую завантажити його в PyPi . Синтаксис, який використовується для README на PyPi, є reStructuredText.

Я хотів би уникнути необхідності обробляти два README, що містять приблизно однаковий вміст; тому я шукав відмітку для перекладача RST (або навпаки), але не зміг знайти жодного.

Я бачу інше рішення - виконати розмітку / HTML, а потім переклад HTML / RST. Я знайшов деякі ресурси для цього тут і тут, так що, мабуть, це можливо.

Чи маєте ви якусь ідею, яка могла б краще відповідати тому, що я хочу зробити?

Я б рекомендував Pandoc , "швейцарський армійський ніж для перетворення файлів з одного формату розмітки в інший" (ознайомтеся з діаграмою підтримуваних перетворень внизу сторінки, це дуже вражає). Pandoc дозволяє розмітці безпосередньо реструктуризувати переклад тексту. Існує також онлайн редактор тут , який дозволяє спробувати його, так що ви можете просто використовувати онлайн редактор для перетворення файлів 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 також підтримує рендеринг 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 у двох форматах.

Ви можете знайти більше інформації про це в документації .

Стара відповідь:

Бібліотека розмітки, яка використовується 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+).

Докладнішу інформацію див. У блозі Дастіна Інграма .

З моїх вимог я не хотів встановлювати 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

Вас також може зацікавити той факт, що можна писати в загальному підмножині, щоб ваш документ вийшов таким же чином, коли він відображався як розмітка або відображався як reStructuredText: https://gist.github.com/dupuy/1855764 ☺

Я зіткнувся з цією проблемою і вирішив її за допомогою двох наступних скриптів bash.

Зауважте, що у мене 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файлів. Навіть незважаючи на те, що це рішення означає, що у вас є і той, mdі rstвін, здавалося, є найменш інвазивним і дозволять отримати будь-яку майбутню підтримку розмітки. Я вважаю за краще це над зміною, 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))