Есть же ридми как в Markdown и настройки

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

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

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

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

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

8 110
python github r-markdown restructuredtext pypi

8 ответов:

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

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

46

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

Они даже поддерживают синтаксис конкретного цвета подсветки с помощью 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 в строку уценки, добавить long_description_content_type="text/markdown" и убедитесь, что вы используете последние оснастки (setuptools 38.6.0+,twine 1.11+).

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

3

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

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

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