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

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

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

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

Не могли бы вы представить, что могло бы лучше соответствовать тому, чем я хочу заниматься?

Я бы порекомендовал Pandoc , «швейцарский армейский нож для преобразования файлов из одного формата разметки в другой» (посмотрите диаграмму поддерживаемых преобразований внизу страницы, она впечатляет). Pandoc позволяет использовать markdown для прямого преобразования текста в текст. Существует также онлайн редактор здесь , который позволяет попробовать его, так что вы можете просто использовать онлайн редактор для преобразования файлов 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 в двух форматах.

Вы можете найти больше информации об этом в документации .

Старый ответ:

Библиотека разметки, используемая 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 - это сервер преобразования документов с 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.

Обратите внимание, что у меня есть 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и an, 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))