Markdown और reStructuredText दोनों में समान README रखें

Question

मेरे पास GitHub पर होस्ट किया गया एक प्रोजेक्ट है। इसके लिए मैंने अपने README को मार्कडाउन सिंटैक्स का उपयोग करते हुए लिखा है ताकि इसे GitHub पर अच्छी तरह से स्वरूपित किया जा सके।

जैसा कि मेरा प्रोजेक्ट पायथन में है, मैं इसे PyPi पर अपलोड करने की योजना भी बना रहा हूं । PyPi पर README के ​​लिए प्रयुक्त सिंटैक्स reStructuredText है।

मैं दो README को संभालने से बचना चाहूंगा जिसमें लगभग समान सामग्री हो; इसलिए मैंने आरएसटी (या आसपास के अन्य तरीके) अनुवादक के लिए एक मार्कडाउन की खोज की, लेकिन कोई भी नहीं मिला।

अन्य समाधान जो मैं देख रहा हूं वह एक मार्कशीट / HTML और फिर एक HTML / RST अनुवाद करना है। मुझे यहाँ और यहाँ के लिए कुछ रिसोर्स मिले इसलिए मुझे लगता है कि यह संभव होना चाहिए।

क्या आपके पास कोई विचार होगा जो मैं करना चाहता हूं उसके साथ बेहतर फिट हो सकता है?

Comments

Github प्रस्तुत करेगा README.rst!

— u0b34a0f6ae

यह नया है फिर :) लेकिन यह जानने के लिए अच्छा है, मैं कोशिश करूँगा!

— jlengrand

यदि आप मार्कडाउन में रीडमी का समर्थन करने के लिए PyPI चाहते हैं, तो कृपया bitbucket.org/pypa/pypi/issue/148/support-markdown-for-readmes

— कर्नल

Answer 1

मैं पंडोक की सिफारिश करूंगा , "एक मार्कअप प्रारूप से फाइलों को दूसरे में बदलने के लिए स्विस-आर्मी चाकू" (पृष्ठ के निचले भाग में समर्थित रूपांतरणों के आरेख की जांच करें, यह काफी प्रभावशाली है)। पंडोक सीधे रूप से अनुवाद करने के लिए मार्कडाउन की अनुमति देता है। यहां एक ऑनलाइन संपादक भी है जो आपको इसे आज़माने की अनुमति देता है, इसलिए आप अपनी README फ़ाइलों को परिवर्तित करने के लिए बस ऑनलाइन संपादक का उपयोग कर सकते हैं।

Comments

जादुई आह्वान है: pandoc --from=markdown --to=rst --output=README.rst README.md

— जोनाथन Eunice

Answer 2

जैसा कि @ क्रिस ने सुझाव दिया है, आप मार्कडाउन को आरएसटी में बदलने के लिए पंडोक का उपयोग कर सकते हैं। यह बस 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=[]
)

यह PyPi पर लंबे विवरण के लिए स्वचालित रूप से README.md को RST में बदल देगा। जब पीपांडोक उपलब्ध नहीं है, तो यह बस रूपांतरण के बिना README.md को पढ़ता है - दूसरों को pypandoc स्थापित करने के लिए मजबूर करने के लिए नहीं जब वे केवल मॉड्यूल का निर्माण करना चाहते हैं, तो PyPi पर अपलोड न करें।

इसलिए आप हमेशा की तरह मार्कडाउन में लिख सकते हैं और RST मेस के बारे में कोई परवाह नहीं करते हैं। ;)

Comments

यह वास्तव में समस्या को हल नहीं करता है, क्योंकि यदि उपयोगकर्ता के पास pandandoc स्थापित नहीं है (जो कि वे संभावित रूप से नहीं करेंगे), तो यह एक त्रुटि देगा, क्योंकि PyPI long_description क्षेत्र को RST होने की उम्मीद करता है। यदि pandandoc उपलब्ध नहीं है, तो आपको long_description को किसी को या खाली स्ट्रिंग पर सेट करना चाहिए।

— शाम

नहीं, यह केवल मेटाडेटा को PyPi पर अपलोड करते समय आवश्यक है (जो केवल मॉड्यूल का डेवलपर कर रहा है, उपयोगकर्ता नहीं)। जब उपयोगकर्ता मॉड्यूल को स्थापित करता है और उसके पास pandandoc स्थापित नहीं होता है तो यह कोई त्रुटि नहीं करता है। मैंने इस उपयोग के मामले को सत्यापित कर दिया है।

— जैकब जिरुटका

यह रनटाइम त्रुटि भी फेंक सकता है। एक सुरक्षित पक्ष पर रहने के लिए मैं try-exceptफ़ंक्शन में करने की सलाह देता हूं ।

— varepsilon

उत्तम! सिर्फ एक चीज - RuntimeError: Missing format!जब तक मैंने लंबोदर को नहीं बदला तब तक मुझे अपवाद मिल रहा था read_md = lambda f: convert(f, 'rst', 'md')। कारण होने के नाते (मैं अनुमान लगा रहा हूं) कि मैंने इसे एक स्ट्रिंग खिलाया है और एक फ़ाइल नहीं है (इसलिए कोई फ़ाइल एक्सटेंशन नहीं)।

— २१:४

@frnhr आपका अनुमान सही है। पंडोक एक फ़ाइल एक्सटेंशन से स्रोत प्रारूप को ऑटोोडेट करने में सक्षम है, लेकिन जब आप इसे एक स्ट्रिंग खिलाते हैं, तो आपको प्रारूप को स्पष्ट रूप से निर्दिष्ट करना होगा।

— जकूब जिरुटका

Answer 3

2019 अपडेट

PyPI वेयरहाउस अब Markdown को भी प्रस्तुत करने का समर्थन करता है ! आपको बस अपने पैकेज कॉन्फ़िगरेशन को अपडेट करने और long_description_content_type='text/markdown'इसे जोड़ने की आवश्यकता है। उदाहरण के लिए:

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

इसलिए, आरईएडीएमई को अब दो स्वरूपों में रखने की आवश्यकता नहीं है।

आप इसके बारे में अधिक जानकारी प्रलेखन में पा सकते हैं ।

पुराना उत्तर:

द मार्कअप GitHub द्वारा इस्तेमाल किया पुस्तकालय reStructuredText का समर्थन करता है। इसका मतलब है कि आप README.rst फ़ाइल लिख सकते हैं।

वे सिंटैक्स विशिष्ट रंग का भी समर्थन करते हैं codeऔर code-blockनिर्देशों का उपयोग करते हुए ( उदाहरण के लिए) )

Answer 4

PyPI अब लंबे विवरणों के लिए Markdown का समर्थन करता है!

में setup.py, सेट long_descriptionएक Markdown स्ट्रिंग के लिए, जोड़ने long_description_content_type="text/markdown"और सुनिश्चित करें कि आप हाल ही में टूलींग का उपयोग कर रहे (बनाना setuptools, 38.6.0+twine 1.11+)।

देखें डस्टिन इनग्राम के ब्लॉग पोस्ट अधिक जानकारी के लिए।

Comments

सुन कर अच्छा लगा! यह देखना दिलचस्प है कि इस मुद्दे के इतिहास को देखते हुए अजगर समुदाय में समय के साथ कितनी प्रगति हुई है :)।

— jlengrand

Answer 5

अपनी आवश्यकताओं के लिए मैं अपने कंप्यूटर में पंडोक स्थापित नहीं करना चाहता था। मैंने डॉकटर का उपयोग किया। Docverter एक दस्तावेज़ रूपांतरण सर्वर है जिसमें इसके लिए पंडोक का उपयोग करके एक HTTP इंटरफ़ेस है।

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

Answer 6

: आप यह भी सच है कि यह एक आम सबसेट में लिखने के लिए इतना है कि अपने दस्तावेज़ में उसी तरह जब markdown के रूप में प्रदान या reStructuredText के रूप में प्रदान बाहर आता है संभव है में रुचि हो सकती https://gist.github.com/dupuy/1855764 ☺

Answer 7

मैं इस समस्या में भाग गया और इसे निम्नलिखित दो बैश लिपियों के साथ हल किया।

ध्यान दें कि मैंने अपने मार्कडाउन में LaTeX को बंडल किया है।

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

मुझे आशा है कि वह मदद करेंगे

Answer 8

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))