Python डॉक्यूमेंटेशन के लिए reStructuredText

Sphinx और Python प्रोजेक्ट्स के लिए Markdown को RST में कन्वर्ट करें

reStructuredText (RST) Sphinx का उपयोग करने वाले Python प्रोजेक्ट्स के लिए मानक डॉक्यूमेंटेशन फॉर्मेट है। जबकि Markdown लिखने के लिए बेहतरीन है, RST तकनीकी डॉक्यूमेंटेशन के लिए शक्तिशाली सुविधाएं प्रदान करता है। Markdown को RST में कन्वर्ट करके, आप Markdown में तेज़ी से लिख सकते हैं और मौजूदा Python डॉक्यूमेंटेशन वर्कफ़्लो के साथ एकीकृत कर सकते हैं।

RST में कन्वर्ट क्यों करें?

Sphinx संगतता - RST Sphinx का मूल फॉर्मेट है
Python इकोसिस्टम - अधिकांश Python डॉक्स RST का उपयोग करते हैं
क्रॉस-रेफरेंस - RST दस्तावेज़ों के बीच मजबूत लिंकिंग का समर्थन करता है
एक्सटेंशन - Sphinx के शक्तिशाली एक्सटेंशन इकोसिस्टम तक पहुंच
Read the Docs - RTD होस्टिंग के साथ सीधा एकीकरण

यह कैसे काम करता है

जब आप Markdown को RST में कन्वर्ट करते हैं, तो आपको उचित RST सिंटैक्स मिलता है:

Introduction
============

This is a paragraph with **bold** and *italic* text.

* First item
* Second item

Code Example
------------

.. code-block:: python

   def greet(name):
       return f"Hello, {name}!"

RST में कन्वर्ट करें

Markdown से RST मैपिंग

Markdown	RST आउटपुट
`# Heading`	`=====` से अंडरलाइन
`## Subheading`	`-----` से अंडरलाइन
`bold`	`bold`
`italic`	`italic`
`code`	``code``
`[text](url)`	`text <url>`_
Code blocks	`.. code-block::`

Sphinx के साथ RST का उपयोग

बुनियादी वर्कफ़्लो

तेज़ लेखन के लिए Markdown में कंटेंट लिखें
Markdown2ANY का उपयोग करके RST में कन्वर्ट करें
RST-विशिष्ट सुविधाएं जोड़ें (डायरेक्टिव, क्रॉस-रेफरेंस)
Sphinx से बिल्ड करें: sphinx-build -b html source/ build/

RST सुविधाएं जोड़ना

कन्वर्शन के बाद, Sphinx डायरेक्टिव के साथ अपने RST को बेहतर बनाएं:

.. note::
   This is a note admonition.

.. warning::
   This is a warning.

.. seealso::
   :doc:`other-document`

सामान्य उपयोग के मामले

API डॉक्यूमेंटेशन

autodoc-जनरेटेड API संदर्भों के साथ एकीकृत करने के लिए README फ़ाइलों और गाइड को RST में कन्वर्ट करें।

ट्यूटोरियल

Markdown में ट्यूटोरियल लिखें, RST में कन्वर्ट करें, फिर API डॉक्यूमेंटेशन के क्रॉस-रेफरेंस जोड़ें।

योगदान गाइड

योगदानकर्ता डॉक्यूमेंटेशन बनाएं जो आपके प्रोजेक्ट के बाकी डॉक्स फॉर्मेट से मेल खाती हो।

RST-विशिष्ट सुविधाएं

कन्वर्शन के बाद, आप RST सुविधाएं जोड़ सकते हैं जो Markdown सपोर्ट नहीं करता:

एडमॉनिशन - नोट, चेतावनी, टिप, खतरा बॉक्स
क्रॉस-रेफरेंस - दस्तावेज़ों और अनुभागों के बीच लिंक
रोल - सिमेंटिक मार्कअप जैसे :func:, :class:
डायरेक्टिव - कस्टम कंटेंट ब्लॉक
Toctrees - दस्तावेज़ पदानुक्रम