Miej ten sam plik README zarówno w Markdown, jak i reStructuredText

116

Mam projekt hostowany na GitHub. W tym celu napisałem plik README przy użyciu składni Markdown, aby ładnie go sformatować na GitHub.

Ponieważ mój projekt jest w Pythonie, planuję również załadować go do PyPi . Składnia używana w plikach README w PyPi to reStructuredText.

Chciałbym uniknąć konieczności obsługi dwóch plików README zawierających z grubsza tę samą zawartość; więc szukałem przeceny na tłumacza RST (lub odwrotnie), ale nie mogłem znaleźć żadnego.

Innym rozwiązaniem, które widzę, jest wykonanie przeceny / HTML, a następnie tłumaczenie HTML / RST. Znalazłem zasoby do tego tutaj i tutaj, więc myślę, że powinno to być możliwe.

Czy miałbyś pomysł, który lepiej pasowałby do tego, co chcę zrobić?

jlengrand
źródło
21
Github wyrenderuje README.rst!
u0b34a0f6ae
To jest więc nowe :) Ale dobrze wiedzieć, spróbuję!
jlengrand
6
Jeśli chcesz, aby PyPI obsługiwał readmes w Markdown, skomentuj żądanie funkcji na bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes
Colonel Panic

Odpowiedzi:

88

Polecam Pandoc , ten „nóż szwajcarskiej armii, do konwersji plików z jednego formatu na inny znaczników” (zobacz schemat obsługiwanych konwersji na dole strony, jest imponująca). Pandoc umożliwia bezpośrednie tłumaczenie reStructuredText za pomocą Markdown. Jest tu również edytor online , który pozwala go wypróbować, więc możesz po prostu użyć edytora online do konwersji plików README.

Chris
źródło
45
Magiczna inwokacja to: pandoc --from=markdown --to=rst --output=README.rst README.md
Jonathan Eunice
47

Jak zasugerował @Chris, możesz użyć Pandoc do konwersji Markdown na RST. Można to po prostu zautomatyzować za pomocą modułu pypandoc i trochę magii w 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=[]
)

Spowoduje to automatyczną konwersję pliku README.md do RST dla długiego opisu używanego na PyPi. Gdy pypandoc nie jest dostępny, to czyta README.md bez konwersji - aby nie zmuszać innych do instalowania pypandoc, gdy chcą tylko zbudować moduł, a nie przesyłać do PyPi.

Możesz więc pisać w Markdown jak zwykle i nie przejmować się już bałaganem RST. ;)

Jakub Jirutka
źródło
To tak naprawdę nie rozwiązuje problemu, ponieważ jeśli użytkownik nie ma zainstalowanego pypandoc (czego prawdopodobnie nie będzie), zgłosi błąd, ponieważ PyPI oczekuje, że pole long_description będzie RST. Jeśli pypandoc nie jest dostępny, należy ustawić long_description na None lub na pusty ciąg.
Cerin
7
Nie, jest to potrzebne tylko podczas przesyłania metadanych do PyPi (co robi tylko programista modułu, a nie użytkownicy). Nie generuje żadnego błędu, gdy użytkownik instaluje moduł i nie ma zainstalowanego pypandoc. Sprawdziłem ten przypadek użycia.
Jakub Jirutka
Może to również spowodować błąd w czasie wykonywania. Aby pozostać po bezpiecznej stronie, polecam zrobić try-exceptw tej funkcji.
varepsilon
1
Idealny! Tylko jedno - otrzymywałem RuntimeError: Missing format!wyjątek, dopóki nie zmieniłem lambdy na read_md = lambda f: convert(f, 'rst', 'md'). Powodem jest (zgaduję), że podałem mu ciąg znaków, a nie plik (więc bez rozszerzenia pliku).
frnhr
@frnhr Twoje przypuszczenie jest poprawne. Pandoc jest w stanie automatycznie wykryć format źródłowy z rozszerzenia pliku, ale kiedy podajesz mu ciąg, musisz jawnie określić format.
Jakub Jirutka
30

Aktualizacja 2019

Magazyn PyPI obsługuje renderowanie Markdown, jak dobrze! Wystarczy zaktualizować konfigurację pakietu i dodać long_description_content_type='text/markdown'do niej plik. na przykład:

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

Dlatego nie ma już potrzeby przechowywania README w dwóch formatach.

Więcej informacji na ten temat znajdziesz w dokumentacji .

Stara odpowiedź:

Plik Markup biblioteka wykorzystywana przez GitHub obsługuje reStructuredText. Oznacza to, że możesz napisać plik README.rst.

Obsługują nawet podświetlanie kolorów specyficzne dla składni przy użyciu dyrektyw codei code-block( przykład )

Cesar Canassa
źródło
6

PyPI obsługuje teraz Markdown dla długich opisów!

W setup.py, ustaw long_descriptionciąg Markdown, dodaj long_description_content_type="text/markdown"i upewnij się, że używasz najnowszych narzędzi ( setuptools38.6.0+,twine 1.11+).

Więcej informacji można znaleźć w poście na blogu Dustina Ingrama .

Petr Viktorin
źródło
Miło słyszeć! Ciekawie jest zobaczyć postępy w społeczności Pythona, przyglądające się historii tego wydania :).
jlengrand
4

Ze względu na moje wymagania nie chciałem instalować Pandoc na moim komputerze. Użyłem docvertera. Docverter to serwer konwersji dokumentów z interfejsem HTTP wykorzystujący do tego celu 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
David Miró
źródło
3

Może Cię również zainteresować fakt, że możliwe jest pisanie we wspólnym podzbiorze, dzięki czemu dokument będzie wyglądał tak samo, gdy jest renderowany jako markdown lub renderowany jako reStructuredText: https://gist.github.com/dupuy/1855764

Zooko
źródło
1

Natknąłem się na ten problem i rozwiązałem go za pomocą dwóch następujących skryptów bash.

Zwróć uwagę, że mam dołączony LaTeX do mojego 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

Przydaje się również do konwersji do formatu 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

Mam nadzieję że to pomogło

Chet
źródło
0

Korzystając z pandocnarzędzia sugerowanego przez innych stworzyłem md2rstnarzędzie do tworzenia rstplików. Mimo że to rozwiązanie oznacza, że ​​masz zarówno opcję, jak mdi rst, wydawało się, że jest najmniej inwazyjne i pozwoliłoby na dodanie jakiejkolwiek przyszłej obsługi przecen. Wolę to od przeróbek, setup.pya może Ty też:

#!/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))
robmuh
źródło