Вопрос по github, python – Иметь один и тот же README как в Markdown, так и в reStructuredText

111

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

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

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

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

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

Если вы хотите, чтобы PyPI поддерживал readmes в Markdown, прокомментируйте запрос функции на Bitbucket.org / pypa / PyPI / вопрос / 148 / Поддержка-уценки-для-файлы README Colonel Panic
Тогда это ново :) Но приятно знать, я попробую! jlengrand
Github будет рендеритьREADME.rst! u0b34a0f6ae

Ваш Ответ

8   ответов
86

Pandoc, «швейцарский армейский нож для преобразования файлов из одного формата разметки в другой» (ознакомьтесь со схемой поддерживаемых преобразований в нижней части страницы, это впечатляет). Pandoc позволяет уценке переводить текст напрямую. Также есть онлайн-редакторВо, который позволяет вам попробовать, так что вы можете просто использовать онлайн-редактор для преобразования ваших файлов README.

Волшебный призыв:pandoc --from=markdown --to=rst --output=README.rst README.md Jonathan Eunice
47

вы можете использовать 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. ;)

Это на самом деле не решает проблему, поскольку, если у пользователя не установлен pypandoc (что, скорее всего, не будет), он выдаст ошибку, так как PyPI ожидает, что поле long_description будет RST. Если pypandoc недоступен, вы должны установить для long_description значение None или пустую строку. Cerin
Отлично! Только одно - я получалRuntimeError: Missing format! исключение, пока я не изменил лямбда наread_md = lambda f: convert(f, 'rst', 'md'). Причина (я предполагаю), что я передал ей строку, а не файл (поэтому нет расширения файла). frnhr
Нет, это нужно только при загрузке метаданных в PyPi (что делает только разработчик модуля, а не пользователи). Он не выдает никакой ошибки, когда пользователь устанавливает модуль, и у него не установлен pypandoc. Я проверил этот вариант использования. Jakub Jirutka
@ frnhr Ваше предположение верно. Pandoc может автоматически определять исходный формат по расширению файла, но когда вы передали ему строку, вы должны явно указать формат. Jakub Jirutka
Это также может вызвать ошибку во время выполнения. Для того, чтобы остаться в безопасности, я рекомендую сделатьtry-except в функции. varepsilon
5

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

Видеть Пост в блоге Дастина Инграма Больше подробностей

Рад слышать! Интересно посмотреть, как со временем в сообществе питонов достигнут прогресс, глядя на историю этой проблемы:). jlengrand
25
2019 Обновление

Склад PyPI теперь поддерживает рендеринг уценки, а также! Вам просто нужно обновить конфигурацию пакета и добавить символ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 в двух форматах.

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

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

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

Они даже поддерживают цветовую подсветку синтаксиса, используяcode а такжеcode-block директивы Приме)

4

Я использовал доквертер. 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

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

1

птов 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

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

0

Используя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))

Похожие вопросы