Имейте тот же README как в Markdown, так и в reStructuredText

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

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

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

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

У вас есть идеи, которые могли бы лучше соответствовать тому, что я хочу сделать?

110
github markdown pypi python restructuredtext

8 ответов

Я бы порекомендовал Pandoc, "swiss-army knife for converting files from one markup format into another" (ознакомьтесь с диаграммой поддерживаемых преобразований в нижней части страницы, это довольно впечатляет). Pandoc позволяет markdown реструктурировать перевод текста напрямую. Существует также онлайн-редактор здесь что позволяет вам попробовать, поэтому вы можете просто использовать онлайн-редактор для преобразования файлов README.

85

Как предложил @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 для первого для длинного описания, используя на PyPi. Когда pypandoc недоступен, тогда он просто читает README.md без преобразования - чтобы не заставлять других устанавливать pypandoc, когда они хотят просто построить модуль, а не загружать в PyPi.

таким образом, вы можете писать в Markdown как обычно и больше не заботиться о первом беспорядке. ;)

46

на разметки библиотека, используемая GitHub, поддерживает reStructuredText. Это означает, что вы можете написать README.файл RST.

Они даже поддерживают подсветку определенного цвета синтаксиса с помощью code и code-block директивы (пример)

22

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

3

для моих требований я не хотел устанавливать 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
3

PyPI теперь поддерживает Markdown для длинных описаний!

на setup.py, set long_description в строку Markdown добавьте long_description_content_type="text/markdown" и убедитесь, что вы используете последние оснастки (setuptools 38.6.0+, twine 1.11+).

посмотреть сообщение в блоге Дастина Ингрэма для получения более подробной информации.

3

я столкнулся с этой проблемой и решили ее с помощью двух следующих сценариев.

обратите внимание, что у меня есть LaTeX в комплекте с моей уценкой.

#!/usr/bin/env bash

if [ $# -lt 1 ]; then
  echo " file.md"
  exit;
fi

filename=$(basename "")
extension="${filename##*.}"
filename="${filename%.*}"

if [ "$extension" = "md" ]; then
  rst=".rst"
  pandoc  -o $filename$rst
fi

его также полезно конвертировать в html. md2html:

#!/usr/bin/env bash

if [ $# -lt 1 ]; then
  echo " file.md <style.css>"
  exit;
fi

filename=$(basename "")
extension="${filename##*.}"
filename="${filename%.*}"

if [ "$extension" = "md" ]; then
  html=".html"
  if [ -z  ]; then
    # if no css
    pandoc -s -S --mathjax --highlight-style pygments  -o $filename$html
  else
    pandoc -s -S --mathjax --highlight-style pygments -c   -o $filename$html
  fi
fi

надеюсь, это поможет

1

С помощью pandoc инструмент, предложенный другими, я создал md2rst утилита для создания rst файлы. Хотя это решение означает, что у вас есть как 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))
0