Имейте тот же README как в Markdown, так и в reStructuredText
У меня есть проект, размещенный на GitHub. Для этого я написал свой README, используя синтаксис Markdown, чтобы он был красиво отформатирован на GitHub.
поскольку мой проект находится в Python, я также планирую загрузить его в PyPi. Синтаксис, используемый для READMEs на PyPi, является reStructuredText.
Я хотел бы избежать необходимости обрабатывать два READMEs, содержащих примерно одинаковый контент; поэтому я искал уценку для первого (или наоборот) переводчика, но не мог найди любого.
другое решение, которое я вижу, - это выполнить уценку / HTML, а затем перевод HTML/RST. Я нашел некоторые ресурсы для этого здесь и здесь поэтому я думаю, что это должно быть возможно.
У вас есть идеи, которые могли бы лучше соответствовать тому, что я хочу сделать?
8 ответов
Я бы порекомендовал Pandoc, "swiss-army knife for converting files from one markup format into another" (ознакомьтесь с диаграммой поддерживаемых преобразований в нижней части страницы, это довольно впечатляет). 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 для первого для длинного описания, используя на PyPi. Когда pypandoc недоступен, тогда он просто читает README.md без преобразования - чтобы не заставлять других устанавливать pypandoc, когда они хотят просто построить модуль, а не загружать в PyPi.
таким образом, вы можете писать в Markdown как обычно и больше не заботиться о первом беспорядке. ;)
вас также может заинтересовать тот факт, что можно писать в общем подмножестве, чтобы ваш документ выходил таким же образом при визуализации как markdown или как reStructuredText:https://gist.github.com/dupuy/1855764 ☺
для моих требований я не хотел устанавливать 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
PyPI теперь поддерживает Markdown для длинных описаний!
на setup.py
, set long_description
в строку Markdown добавьте long_description_content_type="text/markdown"
и убедитесь, что вы используете последние оснастки (setuptools
38.6.0+, twine
1.11+).
посмотреть сообщение в блоге Дастина Ингрэма для получения более подробной информации.
я столкнулся с этой проблемой и решили ее с помощью двух следующих сценариев.
обратите внимание, что у меня есть 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
надеюсь, это поможет
С помощью 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))