RST के बजाय मार्कडाउन के साथ स्फिंक्स का उपयोग करना

212

मुझे RST से नफरत है लेकिन स्फिंक्स से प्यार है। वहाँ एक तरीका है कि स्फिंक्स reStructuredText के बजाय markdown पढ़ता है?

python markdown python-sphinx

— digi604
स्रोत

1

मुझे इसके लिए उपलब्ध किसी भी विकल्प की जानकारी नहीं है। लेकिन ध्यान दें कि RST के पास एक्स्टेंसिबिलिटी के मामले में मार्कडाउन की तुलना में बहुत अधिक विकल्प हैं। तो आपके प्रोजेक्ट के आधार पर यह पर्याप्त नहीं हो सकता है।

— वोल्फ

2

आरएसटी का एक सबसेट है जो ज्यादातर वैध मार्कडाउन है। यदि आप स्फिंक्स फ़ील्ड सूचियों ( :param path:आदि) से नफरत करते हैं , तो नेपोलियन एक्सटेंशन देखें ।

— बेनी चेर्नियाव्स्की-पास्किन

3

यदि आप अपने पाइथन प्रोजेक्ट को मार्कडाउन में स्फिंक्स के साथ दस्तावेज़ करना चाहते हैं, तो bitbucket.org/birkenfeld/sphinx/issue/825/…

— कर्नल पैनिक

1

इस टिप्पणी को देखकर ऐसा लगता है जैसे आप दोनों को मिला सकते हैं: read-the-docs.readthedocs.org/en/latest/…

— Stefan van der Walt

2

बेसिक मार्कडाउन सपोर्ट ने आखिरकार इसे Sphinx में शामिल कर लिया है: नया जवाब

— ओलिवर बेस्टवाल्टर

97

ऐसा करने का "उचित" तरीका है जो मार्कडाउन के लिए एक डॉकुटिल्स पार्सर लिखना होगा । (प्लस पार्सर चुनने के लिए एक स्फिंक्स विकल्प।) इस की सुंदरता सभी डोकुटिल्स आउटपुट प्रारूपों के लिए तत्काल समर्थन होगी (लेकिन आप इस बारे में परवाह नहीं कर सकते हैं, क्योंकि इसी तरह के मार्कडाउन टूल पहले से ही मौजूद हैं)। दृष्टिकोण से बिना पार्सर को विकसित करने के तरीके:

आप धोखा दे सकते हैं और एक "पार्सर" लिख सकते हैं जो पंडोक का उपयोग आरएसटी में मार्कडाउन को बदलने और आरएसटी पार्सर को पास करने के लिए करता है :-)।
आप एक मौजूदा मार्कडाउन-> XML पार्सर का उपयोग कर सकते हैं और परिणाम को बदल सकते हैं (XSLT का उपयोग कर?) Docutils स्कीमा के लिए।
आप कुछ मौजूदा अजगर मार्कडाउन पार्सर ले सकते हैं जो आपको एक कस्टम रेंडर को परिभाषित करने और इसे डॉकुटिल्स नोड ट्री बनाने की सुविधा देता है।
आप मौजूदा RST रीडर को कांटा कर सकते हैं, सब कुछ अप्रासंगिक कर सकते हैं जो मार्कडाउन के लिए अप्रासंगिक है और विभिन्न सिंटैक्स को बदल सकता है ( यह तुलना मदद कर सकती है) ...
संपादित करें: जब तक आप इसे भारी परीक्षण के लिए तैयार नहीं करते हैं, मैं इस मार्ग की अनुशंसा नहीं करता। मार्कडाउन में पहले से ही बहुत अधिक अलग-अलग बोलियाँ हैं और इसके परिणामस्वरूप परिणाम अभी तक एक-दूसरे ...

अद्यतन: https://github.com/sgenoud/remarkdown docutils के लिए एक मार्कशीट रीडर है। यह ऊपर के किसी भी शॉर्टकट को नहीं लेता था, लेकिन खूंटी-मार्कडाउन से प्रेरित एक पार्सले पीईजी व्याकरण का उपयोग करता है ।

अभी तक निर्देशों का समर्थन नहीं करता है ।

अद्यतन: https://github.com/readthedocs/recommonmark और एक अन्य डॉक्यूटिल रीडर है, जो मूल रूप से ReadTheDocs पर समर्थित है। टिप्पणी से व्युत्पन्न लेकिन कॉमनमार्क-पी पार्सर का उपयोग करता है।

यह रूपांतरित हो सकता है एक toctree के लिए लिंक की उचित संरचनाओं जैसे सूची में विशिष्ट अधिक या कम प्राकृतिक Markdown वाक्यविन्यास। * भूमिकाओं के लिए सामान्य देशी वाक्यविन्यास नहीं है।
निर्देशन सहित किसी भी आरएसटी सामग्री को एम्बेड करने का समर्थन करता है, जिसमें एक ```eval_rstअवरुद्ध ब्लॉक के साथ-साथ निर्देशों के लिए एक शॉर्टहैंड भी शामिल है DIRECTIVE_NAME:: ...।

अद्यतन : MyST अभी तक एक और docutins / स्फिंक्स रीडर है। मार्कडाउन-इट-पी के आधार पर, कॉमनमार्क संगत।

{ROLE_NAME}`...`भूमिकाओं के लिए एक सामान्य वाक्यविन्यास है।
```{DIRECTIVE_NAME} ...फ़ेंसिड ब्लॉक वाले निर्देशों के लिए एक सामान्य वाक्यविन्यास है ।

में सभी मामलों में, आप Markdown के एक्सटेंशन का आविष्कार करने का प्रतिनिधित्व करने की आवश्यकता होगी स्फिंक्स निर्देशों और भूमिकाओं । जबकि आपको उन सभी की आवश्यकता नहीं हो सकती है, कुछ .. toctree::आवश्यक हैं।
मुझे लगता है कि यह सबसे कठिन हिस्सा है। स्फिंक्स एक्सटेंशन से पहले reStructuredText पहले ही मार्कडाउन से समृद्ध था। यहां तक कि भारी विस्तारित मार्कडाउन , जैसे कि पैंडॉक , ज्यादातर आरएसटी फीचर सेट का एक सबसेट है। यह कवर करने के लिए बहुत जमीन है!

कार्यान्वयन-वार, सबसे आसान बात यह है कि किसी भी डोकुटिल्स भूमिका / निर्देश को व्यक्त करने के लिए एक सामान्य निर्माण जोड़ रहा है। वाक्यविन्यास प्रेरणा के लिए स्पष्ट उम्मीदवार हैं:

सिंटैक्स को अट्रैक्ट करें, जो पैंडॉक और कुछ अन्य कार्यान्वयन पहले से ही कई इनलाइन और ब्लॉक निर्माणों पर अनुमति देते हैं। उदाहरण के लिए `foo`{.method}-> `foo`:method:।
HTML / एक्सएमएल। से <span class="method">foo</span>सिर्फ docutils आंतरिक एक्सएमएल डालने के kludgiest दृष्टिकोण करने के लिए!
निर्देश के लिए किसी प्रकार का यम?

लेकिन इस तरह की जेनेरिक मैपिंग सबसे मार्कशीट-ईश समाधान नहीं होगी ... वर्तमान में मार्कडाउन एक्सटेंशन पर चर्चा करने के लिए सबसे सक्रिय स्थान https://groups.google.com/forum/# .topic/pandoc-discuss , https: // हैं! github.com/scholmd/scholmd/

इसका मतलब यह भी है कि आप किसी भी तरह से बिना किसी विस्तार के एक पार्सल पार्सर का पुन: उपयोग कर सकते हैं। पंडोक फिर से अपनी प्रतिष्ठा के लिए कस्टम फ़ाइल का समर्थन करके दस्तावेज़ रूपांतरण के स्विस सेना चाकू के रूप में रहता है । (वास्तव में, अगर मैं इसे एप्रोच करता तो मैं डोकुटिल्स रीडर्स / ट्रांसफॉर्मर्स / राइटर्स और पंडोक रीडर्स / फिल्टर्स / राइटर्स के बीच एक जेनेरिक ब्रिज बनाने की कोशिश करता। यह आपकी जरूरत से ज्यादा है लेकिन पेऑफ सिर्फ स्फिंक्स / से ज्यादा चौड़ी होगी। markdown।)

वैकल्पिक पागल विचार: स्फिंक्स को संभालने के लिए मार्कडाउन का विस्तार करने के बजाय, reStructuredText का समर्थन करें (ज्यादातर) मार्काडाउन का एक सुपरसेट! सौंदर्य आप किसी भी स्फिंक्स सुविधाओं का उपयोग करने में सक्षम होंगे, जैसा कि अभी भी मार्कडाउन में अधिकांश सामग्री लिखने में सक्षम है।

पहले से ही काफी वाक्यविन्यास ओवरलैप है ; सबसे विशेष रूप से लिंक सिंटैक्स असंगत है। मुझे लगता है कि यदि आप मार्कडाउन लिंक, और ###-स्टाइल हेडर के लिए आरएसटी में समर्थन जोड़ते हैं, और डिफ़ॉल्ट `backticks`भूमिका को शाब्दिक रूप से बदलते हैं , और शायद शाब्दिक ब्लॉक का मतलब शाब्दिक अर्थ (आरटीएस > ...उद्धरणों के लिए समर्थन ) से बदल जाता है, तो आपको कुछ उपयोगी मिलेगा जो सबसे अधिक मार्कडाउन है। ।

— बेनी चेर्नियाव्स्की-पास्किन
स्रोत

17

मैं इस क्षेत्र में प्रगति की कमी से निष्कर्ष निकालता हूं, आरएसटी केवल पर्याप्त रूप से अच्छा हो सकता है और पर्याप्त रूप से भिन्न नहीं हो सकता है ताकि इस तरह के उपक्रम को इसके लायक बनाया जा सके।

— प्रो। फल्केन

5

TLDR: उपयोग recommonmark Markdown का उपयोग कर स्फिंक्स प्रलेखन लिखने के लिए।

— ओस्ट्रोकैच

myst-parserइस उत्तर में नया जोड़ने का सुझाव दें । यह जीतने वाला है।

— रिक

92

आप उसी Sphinx प्रोजेक्ट में Markdown और reStructuredText का उपयोग कर सकते हैं। यह कैसे किया जाता है यह पूरी तरह से डॉक्स पर पढ़ें ।

सिफ़ारिश ( pip install recommonmark) स्थापित करें और फिर संपादित करें conf.py:

from recommonmark.parser import CommonMarkParser

source_parsers = {
    '.md': CommonMarkParser,
}

source_suffix = ['.rst', '.md']

मैंने गितुब (सेरा / स्फिंक्स-विथ-मार्कडाउन) पर एक छोटा सा उदाहरण प्रोजेक्ट बनाया है जिसमें यह दिखाया गया है कि यह (और वह) कैसे काम करता है। इसमें कॉमनमार्क 0.5.4 और सिफ़ारिशी 0.4.0 का उपयोग किया गया है।

— Marijn
स्रोत

4

बेनी इस दृष्टिकोण का उल्लेख अपने बहुत व्यापक उत्तर में करते हैं । हालाँकि, मुझे लगता है कि यह प्रश्न इस सरल उत्तर के योग्य है।

— मेराज

2

यह पढ़ने के लिए महत्वपूर्ण है recommonmark.readthedocs.org/en/latest/auto_structify.html एक toctree बनाने के लिए विशेष रूप से कैसे, और कैसे उपयोग करने के लिए, eval_rstबाड़ लगी हुई ब्लॉक किसी भी पहला निर्माण / निर्देश डालने के लिए।

— बेनी चेर्नियाव्स्की-पास्किन

इसके लिए रिकमेंडमार्क और कॉमनमार्क स्थापित करना आवश्यक है

— XavierCLL

1

मुझे ImportError: cannot import name 'DocParser'स्फिंक्स 1.4.1 के तहत स्फिंक्स 1.4.1 पर मिलता है ।

— detly

2

@detly: ImportError आम संस्करण के नवीनतम संस्करण (0.6.0) की सिफारिश के साथ संगतता को तोड़ने के कारण है: github.com/rtfd/recommonmark/issues/24 देखें । समाधान:pip install commonmark==0.5.5 --upgrade

— kadee

30

यह Sphinx का उपयोग नहीं करता है, लेकिन MkDocs Markdown का उपयोग करके आपके दस्तावेज़ का निर्माण करेगा। मुझे भी rst से नफरत है, और वास्तव में अब तक MkDocs का आनंद लिया है।

— jkmacc
स्रोत

5

एंड-यूज़र डॉक्यूमेंटेशन के लिए MkDocs ने यहाँ भी बहुत अच्छा काम किया है। अभी भी डॉकस्ट्रिंग्स के भीतर मार्कडाउन का उपयोग करना चाहते हैं ..

— मार्कस ओटोसन

2

इसके लिए इतना हां।

— jkmacc

1

अरे, धन्यवाद - MkDocs कमाल है! मैंने Sphinx और RST की तुलना में बहुत सारी शक्ति और सुविधाएँ ढीली कर दी हैं, यह सुनिश्चित करने के लिए है ... लेकिन यह बहुत सरल, सरल, सरल और उपयोग में आसान है। मेरे उपयोग के लगभग सभी मामलों के लिए एकदम सही है - जैसे लघु इंस्टॉलेशन निर्देश और कुछ उदाहरणों के साथ कुछ क्विक स्टार्ट ट्यूटोरियल। कुछ मामलों के लिए, जहां मुझे समझाने के लिए बहुत सारे स्रोत कोड की आवश्यकता होती है - ig वर्ग और फ़ंक्शन कॉल प्रलेखन - हालांकि मैं स्फिंक्स के साथ छड़ी करता हूं।

— ब्रूटस

इसे लिखते समय, यह टीओसी इंडेंटेशन के केवल 2 स्तरों का समर्थन करता है।

— व्रिजियल

@wrygiel आप बहुत सही नहीं हैं - TOC स्तरों की संख्या आपके द्वारा उपयोग किए जा रहे विषय पर निर्भर करती है।

— एएल

27

अद्यतन: यह अब आधिकारिक तौर पर स्फिंक्स डॉक्स में समर्थित और प्रलेखित है ।

ऐसा लगता है कि मूल कार्यान्वयन ने इसे स्फिंक्स में बदल दिया है लेकिन शब्द ने अभी तक गोल नहीं किया है। गितुब मुद्दा टिप्पणी देखें

निर्भरता स्थापित करें:

pip install commonmark recommonmark

समायोजित करें conf.py:

source_parsers = {
    '.md': 'recommonmark.parser.CommonMarkParser',
}
source_suffix = ['.rst', '.md']

— ओलिवर बेस्टवाल्टर
स्रोत

1

यदि आपको मिलता है cannot import name DocParser, तो प्रयास करें pip install commonmark==0.5.5।

— रोजर डेल

1

स्फिंक्स डॉक्स में लिंक sphinx-doc.org/en/master/usage/markdown.html

— पॉल ब्रैनन

21

मार्कडाउन और रेस्ट अलग-अलग चीजें करते हैं।

RST दस्तावेजों के साथ काम करने के लिए एक वस्तु मॉडल प्रदान करता है।

मार्कडाउन पाठ के बिट्स को उकेरने का एक तरीका प्रदान करता है।

यह उचित लगता है कि आप अपने स्फिंक्स प्रोजेक्ट से मार्कडाउन सामग्री के बिट्स को संदर्भित करना चाहते हैं, आरएसटी का उपयोग करके समग्र सूचना वास्तुकला और बड़े दस्तावेज़ के प्रवाह को रोकना है। मार्कडाउन को वह करने दें, जो लेखकों को पाठ लिखने पर ध्यान केंद्रित करने की अनुमति देता है।

क्या एक मार्कडाउन डोमेन को संदर्भित करने का एक तरीका है, जैसे कि सामग्री को उत्कीर्ण करना है? लगता है कि RST / स्फिंक्स ने toctreeउन्हें मार्कडाउन में नकल किए बिना सुविधाओं का ध्यान रखा है ।

— bewest
स्रोत

5

"अपने स्फिंक्स प्रोजेक्ट से मार्कडाउन सामग्री के अपने बिट्स को संदर्भित करना चाहते हैं।" - यह वास्तव में मैं क्या करना चाहता हूं; मैं README.mdअपने अधिक व्यापक स्फिंक्स प्रलेखन में कुछ मार्कडाउन सामग्री (मेरे ) को शामिल करना चाहता हूं । क्या आप जानते हैं कि क्या यह संभव है?

— detly

9

यह अब आधिकारिक रूप से समर्थित है: http://www.sphinx-doc.org/en/stable/markdown.html

— मेहरबान
स्रोत

8

मैं इस कार्य के लिए पेन्डो का उपयोग करने के बेनी के सुझाव के साथ गया था। एक बार इनस्टॉल करने के बाद निम्न स्क्रिप्ट सोर्स मार्किंग में सभी डायरेक्टरी फाइलों को rst फाइल्स में बदल देगी, ताकि आप मार्कडाउन में अपने सभी डॉक्यूमेंट को लिख सकें। आशा है कि यह दूसरों के लिए उपयोगी है।

#!/usr/bin/env python
import os
import subprocess

DOCUMENTATION_SOURCE_DIR = 'documentation/source/'
SOURCE_EXTENSION = '.md'
OUTPUT_EXTENSION = '.rst'

for _, __, filenames in os.walk(DOCUMENTATION_SOURCE_DIR):
    for filename in filenames:
        if filename.endswith('.md'):
            filename_stem = filename.split('.')[0]
            source_file = DOCUMENTATION_SOURCE_DIR + filename_stem + SOURCE_EXTENSION
            output_file = DOCUMENTATION_SOURCE_DIR + filename_stem + OUTPUT_EXTENSION
            command = 'pandoc -s {0} -o {1}'.format(source_file, output_file)
            print(command)
            subprocess.call(command.split(' '))

— igniteflow
स्रोत

1

वर्कअराउंड है।
Sphinx-quickstart.py स्क्रिप्ट मेकफाइल बनाती है।
मार्कडाउन को reStructiveText में परिवर्तित करने के लिए आप आसानी से पंडोक को हर बार मेकफाइल से आमंत्रित कर सकते हैं।

— the_drow
स्रोत

3

जब तक मैं कुछ गलत नहीं कर रहा हूं, तब तक रेस्क्यू को मार्कडाउन से बदलना आसान नहीं है। यदि आप मार्कडाउन स्रोत फ़ाइल में टार्कट्री जैसे निर्देशों का उपयोग करते हैं , तो पंडोक उन्हें एक ही पंक्ति में बदल देगा: .. toctree:: :maxdepth: 2 :glob:परिवर्तन के दौरान और वे काम करना बंद कर देंगे। दूसरे शब्दों में, इस तरह से निर्देशों का उपयोग करना असंभव है।

— विकटोर वाल्क

@WiktorWalc मैं pandoc से बहुत परिचित नहीं हूँ और मैंने वास्तव में इसकी कोशिश नहीं की है, लेकिन इसका मतलब है कि मुझे लगता है। ओह अच्छा। मैंने कोशिश की। मुझे लगता है कि आप बग रिपोर्ट दर्ज कर सकते हैं?

— the_drow

@IktorWalc: ..toctreeमान्य मार्कडाउन सिंटैक्स नहीं है। आप या तो पूरे दस्तावेज को मार्कडाउन में लिखें (और ReSt की बारीकियों को ढीला करें), या आप ReST का उपयोग करें। आप अपना केक नहीं खा सकते हैं और इसे भी खा सकते हैं।

— आदित्य

1

बस एक संकेत: एक समाधान उन विशेष निर्देशों को छोड़ने के लिए और आउटपुट पीढ़ी में जैसा है, उन्हें छोड़ने के लिए पैंडॉक फिल्टर का उपयोग करना होगा। हालांकि, मैं पंडोक फ़िल्टर का जादूगर नहीं हूं, और यह योजना में अतिरिक्त जटिलता जोड़ता है।

— 19

1

यहाँ एक नया विकल्प है। MyST मार्कडाउन में कुछ विशेषताएं जोड़ता है जो स्फिंक्स को rst करता है जैसे डॉक्स बनाने की अनुमति देता है। https://myst-parser.readthedocs.io/en/latest/

— jkmacc
स्रोत

बस इस का उपयोग शुरू कर दिया है और यह शानदार है।

— रिक

0

ध्यान दें कि भवन निर्माण दस्तावेज मावेन का उपयोग करके और एम्बेडेड स्फिंक्स + Markdown समर्थन पूरी तरह से निम्नलिखित Maven प्लगइन द्वारा समर्थित है:

https://trustin.github.io/sphinx-maven-plugin/index.html

<plugin>
  <groupId>kr.motd.maven</groupId>
  <artifactId>sphinx-maven-plugin</artifactId>
  <version>1.6.1</version>
  <configuration>
    <outputDirectory>${project.build.directory}/docs</outputDirectory>
  </configuration>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>generate</goal>
      </goals>
    </execution>
  </executions>
</plugin>

— Donatello
स्रोत