अपने पायथन कोड का दस्तावेजीकरण करने के लिए स्फिंक्स को कैसे सेट करें

दस्तावेज़ बनाने के लिए स्फिंक्स सबसे लोकप्रिय उपकरणों में से एक है। पायथन समुदाय में, डेवलपर्स इस मुफ्त और ओपन-सोर्स सॉफ़्टवेयर का उपयोग करते हैं। यह सीधे आपके कोड या मार्कडाउन फ़ाइलों से पाठ निकाल सकता है और फिर इसका उपयोग सादे पाठ, HTML, PDF और EPUB जैसे विभिन्न स्वरूपों में दस्तावेज़ बनाने के लिए कर सकता है।

स्फिंक्स की स्थापना

स्फिंक्स को स्थापित करने से पहले, यह देखें कि यह क्या करता है और इसकी कुछ मुख्य विशेषताएं क्या हैं।

स्फिंक्स क्या है और यह क्या करता है?

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

स्फिंक्स में शामिल कुछ विशेषताएं हैं:

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

स्फिंक्स स्थापित करना

स्फिंक्स स्थापित करने से पहले, सुनिश्चित करें कि आपके पास है पायथन 3 आपके विकास के वातावरण में स्थापित है। फिर आप अपने टर्मिनल में निम्नलिखित कमांड चलाकर स्फिंक्स को स्थापित करने के लिए पिप पैकेज मैनेजर का उपयोग कर सकते हैं:

पिप स्फिंक्स स्थापित करें

यह स्फिंक्स और इसकी निर्भरताओं को डाउनलोड और इंस्टॉल करेगा।

स्थापना के बाद, कमांड प्रॉम्प्ट पर निम्न चलाएँ।

स्फिंक्स-बिल्ड --version

अगर सब कुछ ठीक रहा, तो आपको अभी-अभी इंस्टॉल किए गए स्फिंक्स पैकेज के लिए संस्करण संख्या देखनी चाहिए।

एक नया स्फिंक्स प्रोजेक्ट बनाना

एक बार जब आप स्फिंक्स स्थापित कर लेते हैं, तो अपनी कार्यशील निर्देशिका पर जाएँ और एक नया स्फिंक्स प्रोजेक्ट बनाने के लिए स्फिंक्स-क्विकस्टार्ट कमांड चलाएँ।

sphinx-quickstart

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

यदि आप अपनी निर्देशिका की सामग्री सूचीबद्ध करते हैं, तो आप देखेंगे कि यह आदेश आपके लिए कुछ फ़ाइलें बनाता है। Conf.py में कॉन्फ़िगरेशन मान शामिल हैं और index.rst आपके दस्तावेज़ के स्वागत पृष्ठ के रूप में कार्य करता है। निर्माण निर्देशिका जनरेट किए गए दस्तावेज़ों को होस्ट करेगी, और दस्तावेज़ बनाने के लिए Sphinx मेकफ़ाइल (Windows पर Make.bat) का उपयोग करता है।

स्फिंक्स का प्रयोग करते हुए प्रलेखन लिखना

आपकी निर्देशिका की जड़ में index.rst फ़ाइल आपके एप्लिकेशन का होम पेज है। तो, इसे वीएस कोड जैसे टेक्स्ट एडिटर के साथ खोलें- या कोई अन्य अच्छा, मुफ्त कोड संपादक—इसे संपादित करने के लिए।

जैसा कि आप फिट देखते हैं आप index.rst को बदल सकते हैं लेकिन एक चीज जो कम से कम होनी चाहिए वह है रूट टोक्ट्री (सामग्री ट्री की तालिका) निर्देश। यह आवश्यक है क्योंकि यह कई फाइलों को दस्तावेजों के एकल पदानुक्रम से जोड़ता है।

index.rst फ़ाइल में दस्तावेज़ीकरण जोड़ने के लिए, आप RST मार्कअप का उपयोग कर सकते हैं।

एक उदाहरण के रूप में, math_utils मॉड्यूल के लिए index.rst फ़ाइल पर विचार करें। इस फ़ाइल में मॉड्यूल के उद्देश्य का एक संक्षिप्त अवलोकन और सामग्री की तालिका शामिल हो सकती है जो प्रलेखन के अन्य पृष्ठों से लिंक करती है।

मैथ यूटिल्स में आपका स्वागत है
.. टोक्ट्री ::
: अधिकतम गहराई: 2
शुरू करना

इस मॉड्यूल का उपयोग करने के लिए, आपको निम्नलिखित की आवश्यकता होगी:
* पायथन स्थापित।
* एक पाठ संपादक
गणित उपयोगिताएँ

`गणित-बर्तन` मॉड्यूल बुनियादी गणित कार्य प्रदान करता है जैसे जोड़ और
घटाव।

आप आवश्यकतानुसार और .rst फ़ाइलें जोड़ सकते हैं। उदाहरण के लिए, आप निम्नलिखित योगदान दिशानिर्देशों वाली एक फ़ाइल में योगदान मार्गदर्शिका बना सकते हैं, जिसका नाम है योगदान.rst।

योगदान गाइड
हम अपनी परियोजना में योगदान का स्वागत करते हैं! के लिए यहां कुछ दिशानिर्देश दिए गए हैं
योगदान:
- गिटहब पर प्रोजेक्ट को फोर्क करें।
- एक नई शाखा पर अपने परिवर्तन करें।
- यह सुनिश्चित करने के लिए परीक्षण लिखें कि आपके परिवर्तन सही ढंग से काम करते हैं।
- अपने परिवर्तनों के साथ पुल अनुरोध सबमिट करें।
- कोई भी अनुरोधित परिवर्तन करें।
योगदान देने के लिए धन्यवाद!

फिर आप इस फ़ाइल को toctree निर्देश में एक नया खंड जोड़कर index.rst से लिंक कर सकते हैं:

.. टोक्ट्री ::
: अधिकतम गहराई: 2
 :caption: सामग्री की तालिका

 योगदान

यह सामग्री की तालिका में योगदान नाम से एक नया आइटम बनाता है जो क्लिक करने पर उपयोगकर्ता को योगदान पृष्ठ पर ले जाता है।

एक बार जब आप दस्तावेज़ लिख लेते हैं, तो अगला चरण इसे बनाने का होता है। यहां, प्रलेखन के निर्माण का अर्थ है आरएसटी फाइलों से एचटीएमएल, मैनुअल या पीडीएफ पेज तैयार करना।

प्रलेखन का निर्माण

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

एचटीएमएल बनाओ

आपको HTML फ़ाइलों को बिल्ड फ़ोल्डर में देखना चाहिए। यदि निर्माण के दौरान त्रुटियां थीं, तो स्फिंक्स आपको टर्मिनल में बताएगा।

दस्तावेज़ीकरण देखने के लिए, अपने ब्राउज़र में index.html फ़ाइल खोलें:

आपको सामग्री की तालिका से योगदान मार्गदर्शिका पर नेविगेट करने में सक्षम होना चाहिए।

दस्तावेज़ीकरण को अनुकूलित करना

अभी, प्रलेखन में कुछ बुनियादी शैली है। यदि आप इसे अनुकूलित करना चाहते हैं, तो शायद अपने ब्रांड रंग जोड़कर, या यहां तक ​​कि एक डार्क मोड जोड़कर, आप अन्य को स्थापित और उपयोग कर सकते हैं बिल्ट-इन थीम या अपनी खुद की कस्टम थीम बनाएं।

प्रदर्शित करने के लिए, विषय को प्रकृति नामक विषय में बदलने का प्रयास करें:

1. अपनी Sphinx प्रोजेक्ट निर्देशिका में Sphinx कॉन्फ़िगरेशन फ़ाइल conf.py खोलें।
2. उस रेखा को देखें जो html_theme विकल्प को परिभाषित करती है और इसे प्रकृति में बदलें
3. कॉन्फ़िगरेशन फ़ाइल सहेजें और अपने परिवर्तनों को देखने के लिए दस्तावेज़ों का पुनर्निर्माण करें।

दस्तावेज़ीकरण का मुखपृष्ठ इस तरह दिखना चाहिए।

यदि आप बिल्ट-इन थीम का उपयोग नहीं करना चाहते हैं, तो आप हमेशा एक का उपयोग कर सकते हैं तृतीय-पक्ष स्फिंक्स थीम बजाय।

डॉकस्ट्रिंग्स का उपयोग करके अपने कोड का दस्तावेजीकरण

Sphinx आपके द्वारा RST फ़ाइलों में लिखे गए पाठ से आपका Python दस्तावेज़ तैयार करता है। जबकि यह कुछ मामलों में पर्याप्त है, आप मॉड्यूल स्तर पर अपने कोड में डॉकस्ट्रिंग का उपयोग करना चाह सकते हैं।

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