Tôi có một dự án được lưu trữ trên GitHub. Đối với điều này, tôi đã viết README của mình bằng cách sử dụng cú pháp Markdown để có định dạng độc đáo trên GitHub.

Vì dự án của tôi bằng Python nên tôi cũng dự định tải nó lên PyPi . Cú pháp được sử dụng cho README trên PyPi là reStructuredText.

Tôi muốn tránh phải xử lý hai README có nội dung gần giống nhau; vì vậy tôi đã tìm kiếm một trình dịch đánh dấu cho RST (hoặc ngược lại), nhưng không thể tìm thấy bất kỳ.

Giải pháp khác mà tôi thấy là thực hiện đánh dấu / HTML và sau đó là bản dịch HTML / RST. Tôi đã tìm thấy một số nguồn cung cấp cho điều này ở đây và ở đây vì vậy tôi đoán nó sẽ có thể.

Bạn có ý tưởng nào có thể phù hợp hơn với những gì tôi muốn làm không?

Tôi muốn giới thiệu Pandoc , "con dao quân đội Thụy Sĩ để chuyển đổi tệp từ định dạng đánh dấu này thành định dạng đánh dấu khác" (hãy xem sơ đồ chuyển đổi được hỗ trợ ở cuối trang, nó khá ấn tượng). Pandoc cho phép đánh dấu để dịch trực tiếp reStructuredText. Ngoài ra còn có một trình soạn thảo trực tuyến ở đây cho phép bạn dùng thử, vì vậy bạn chỉ có thể sử dụng trình biên tập trực tuyến để chuyển đổi các file README của bạn.

Như @Chris đã đề xuất, bạn có thể sử dụng Pandoc để chuyển đổi Markdown thành RST. Điều này có thể được tự động hóa đơn giản bằng cách sử dụng mô-đun pypandoc và một số phép thuật trong 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=[]
)

Điều này sẽ tự động chuyển đổi README.md thành RST cho phần mô tả dài sử dụng trên PyPi. Khi không có pypandoc , nó chỉ đọc README.md mà không cần chuyển đổi - để không buộc người khác cài đặt pypandoc khi họ chỉ muốn xây dựng mô-đun, không tải lên PyPi.

Vì vậy, bạn có thể viết trong Markdown như bình thường và không quan tâm đến mớ hỗn độn RST nữa. ;)

Cập nhật 2019

PyPI Warehouse hiện cũng hỗ trợ hiển thị Markdown! Bạn chỉ cần cập nhật cấu hình gói của mình và thêm long_description_content_type='text/markdown'vào đó. ví dụ:

setup(
    name='an_example_package',
    # other arguments omitted
    long_description=long_description,
    long_description_content_type='text/markdown'
)

Do đó, không cần phải giữ README ở hai định dạng nữa.

Bạn có thể tìm thêm thông tin về nó trong tài liệu .

Câu trả lời cũ:

Các Markup thư viện sử dụng bởi GitHub hỗ trợ reStructuredText. Điều này có nghĩa là bạn có thể viết tệp README.rst.

Chúng thậm chí còn hỗ trợ tô sáng màu cụ thể theo cú pháp bằng cách sử dụng các lệnh codevà code-block( Ví dụ )

PyPI hiện hỗ trợ Markdown cho các mô tả dài!

Trong setup.py, đặt thành long_descriptionchuỗi Markdown, thêm long_description_content_type="text/markdown"và đảm bảo rằng bạn đang sử dụng công cụ gần đây ( setuptools38.6.0+, twine1.11+).

Xem bài đăng trên blog của Dustin Ingram để biết thêm chi tiết.

Đối với các yêu cầu của tôi, tôi không muốn cài đặt Pandoc trong máy tính của mình. Tôi đã sử dụng docverter. Docverter là một máy chủ chuyển đổi tài liệu với giao diện HTTP sử dụng Pandoc cho việc này.

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

Bạn cũng có thể quan tâm đến thực tế là có thể viết trong một tập hợp con chung để tài liệu của bạn xuất hiện giống như khi được hiển thị dưới dạng markdown hoặc được kết xuất dưới dạng reStructuredText: https://gist.github.com/dupuy/1855764 ☺

Tôi đã gặp sự cố này và giải quyết nó bằng hai tập lệnh bash sau đây.

Lưu ý rằng tôi đã đóng gói LaTeX vào Markdown của mình.

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

Nó cũng hữu ích để chuyển đổi sang 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

Tôi hy vọng điều đó sẽ giúp

Sử dụng pandoccông cụ do những người khác đề xuất, tôi đã tạo một md2rsttiện ích để tạo rsttệp. Mặc dù giải pháp này có nghĩa là bạn có cả một mdvà một rstnó dường như là ít xâm lấn nhất và sẽ cho phép bất kỳ hỗ trợ đánh dấu nào trong tương lai được thêm vào. Tôi thích nó hơn là thay đổi setup.pyvà có thể bạn cũng sẽ:

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