इस पृष्ठ पर

Guidedog / दस्तावेज़ 0.2.0

Sphinx के साथ संगतता

परियोजना का माइग्रेशन आसान बनाने के लिए Guidedog उपयोगी जगहों पर Sphinx का अनुसरण करता है। संगतता हर सुविधा के लिए अलग जाँची जाती है। Python कॉन्फ़िगरेशन या मनमाने Python एक्सटेंशन नहीं चलते। सफल बिल्ड, बिल्ड होने का प्रमाण है; पूरी समानता का नहीं।

परियोजना और प्रकाशन

तालिका 20 परियोजना के काम

काम	लागू व्यवहार
परियोजना संरचना और बिल्ड विकल्प	Sphinx जैसे स्रोत और आउटपुट निर्देशिका विकल्प: -a -E -W -n -D -t -j -b -M -c -C।
कॉन्फ़िगरेशन	परिचित Sphinx नामों के साथ TOML डेटा। माइग्रेशन लिटरल बदलता है और गणना वाले मानों की सूचना देता है।
HTML बिल्डर	html, dirhtml और singlehtml। एकल पृष्ठ के एंकर में दस्तावेज़ का नाम शामिल होता है।
अन्य बिल्डर	text, gettext और dummy। pdf में Typst इस्तेमाल होता है; latex और latexpdf भी इसी रास्ते को चुनते हैं।
टेम्पलेट	Guidedog का Jinja कार्यान्वयन, टाइप वाला html_context, लेआउट इनहेरिटेंस और अतिरिक्त पृष्ठ।
इन्क्रिमेंटल बिल्ड	स्रोत, निर्भरताएँ, टेम्पलेट, कॉन्फ़िगरेशन और संदर्भ खोज बदलने पर संबंधित आउटपुट अमान्य होता है।
प्रकाशन	एक पूरी आउटपुट पीढ़ी प्रकाशित होती है। बिल्ड विफल होने पर पिछली प्रकाशित पीढ़ी बनी रहती है।

-D बूलियन के लिए true और false या 1 और 0 स्वीकार करता है। index न हो और contents हो तो चेतावनी के साथ उसे रूट बना सकते हैं। अतिरिक्त टेम्पलेट पृष्ठ साइट के रूट में फ़ाइलों के रूप में आते हैं, dirhtml में भी। ठीक नियम टेम्पलेट में हैं।

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

epub, man, texinfo, linkcheck, doctest, coverage और changes बिल्डर उपलब्ध नहीं हैं। इनके नाम देने पर सुधार का संदेश मिलता है। रिपॉज़िटरी का tools/linkcheck अलग सत्यापन टूल है।

स्रोत भाषा

तालिका 21 निश्चित संस्करण की अनुरूपता जाँच

रीडर	प्रमाण और सीमाएँ
reStructuredText	कॉर्पस के 98 स्रोतों में तुलना किए गए Docutils वृक्ष और पहचानकर्ता मेल खाते हैं। स्रोत स्थान और कुछ आंतरिक प्रबंधन गुण तुलना में नहीं आते।
CommonMark 0.31.2	विनिर्देश के सभी 652 उदाहरण पास होते हैं।
MyST 0.16.1 reference	218 रीडर टेस्ट केस में 215 और 10 Sphinx बिल्ड केस में 8 मेल खाते हैं। बाकी अंतर दर्ज हैं।

इन टेस्ट के संस्करण निश्चित हैं। ये हर बाद के संस्करण से संगतता नहीं बताते। चल रहे प्रोग्राम के रीडर और रेंडरर की जाँच के प्रमाण के लिए guidedog formats चलाएँ। रीडर निर्देशिकाओं में भी अनुरूपता संबंधी टिप्पणियाँ हैं।

rst_prolog आरंभिक ग्रंथसूची फ़ील्ड के बाद आता है। rst_epilog स्रोत के बाद आता है। दोनों Markdown में नहीं जुड़ते। only और ifconfig शर्त सही होने पर अपने खंड रखते हैं। शर्त वाला खंड आसपास का स्तर बदले तो उसका स्थान Sphinx से अलग हो सकता है। MyST के eval-rst में खंड शीर्षक त्रुटि हैं।

संदर्भ और डोमेन

Guidedog में toctree, लेबल, शब्दावली, खंड और चित्र क्रमांकन तथा ref, doc, numref, term, download, any, keyword, option, envvar और token संदर्भ लागू हैं। ऑब्जेक्ट विषय-सूची वृक्ष, साइडबार और पृष्ठ रूपरेखा में आ सकते हैं।

मानक, Python, C, C++, JavaScript, reStructuredText और गणित डोमेन लागू हैं। Odin डोमेन Guidedog का अपना एक्सटेंशन है। यह पैकेज, घोषणाएँ, सिग्नेचर और बने हुए API पृष्ठ दर्शाता है। केवल स्रोत से खोज और उसकी सीमाएँ Odin के दस्तावेज़ बनाना में हैं।

पैरामीटर, रिटर्न, अपवाद और वेरिएबल फ़ील्ड से संरचित विवरण बनता है। कैनोनिकल नाम संदर्भों और इन्वेंटरी में एलियस बनते हैं। Python के डिफ़ॉल्ट और एनोटेशन स्रोत का रूप रखते हैं। Sphinx इन्हें Python unparser से दोबारा लिख सकता है। C++ घोषणाएँ Sphinx-संगत पहचानकर्ता संस्करण और सिंबल इन्वेंटरी प्रकाशित करती हैं। नेस्टिंग की सीमाएँ लागू हैं। नेस्टेड कोष्ठक रैखिक समय में पार्स होते हैं।

numref एक संख्या स्थान बदलता है और बिना क्रमांक वाले लक्ष्य की सूचना देता है। खंड पढ़ने के क्रम में क्रमांकित होते हैं। दस्तावेज़ को एक बार क्रमांक मिलता है; दूसरी क्रमांकित toctree टकराव बताती है। फ़ॉर्मैट प्रतिस्थापन और पहचानकर्ता के विवरण संदर्भ टेस्ट में देखें।

सामान्य इंडेक्स, मॉड्यूल इंडेक्स और खोज बिल्ट-इन हैं। खोज शब्द के आरंभ से मिलान करती है; Sphinx का अंग्रेज़ी स्टेमिंग नहीं दोहराती।

घोषणात्मक ऑब्जेक्ट टाइप कई उपयोगी Python एक्सटेंशन पंजीकरण की जगह लेते हैं। object_types, crossref_types और directive_aliases उनका डेटा देते हैं। कस्टम Python parse_node को नाम, प्रदर्शन और प्रोग्राम के घोषणात्मक नियमों में बदलते हैं। माइग्रेशन वह कोड बताता है जिसे व्यक्त नहीं कर सकता। ऑब्जेक्ट टाइप घोषित करना देखें।

बिल्ट-इन एक्सटेंशन का व्यवहार

तालिका 22 एक्सटेंशन की सीमा

व्यवहार	स्थिति
todo, ifconfig, extlinks, autosectionlabel	बिल्ट-इन हैं। सीधे लिखे extlinks के लिए उपयुक्त रोल सुझाया जा सकता है।
graphviz	लिंक किया गया Graphviz स्थिर आरेख बनाता है। संसाधन सीमाएँ लागू होती हैं।
intersphinx	स्थानीय और डाउनलोड की गई इन्वेंटरी। Windows पर अभी केवल स्थानीय फ़ाइलें समर्थित हैं।
githubpages	स्थिर साइट के प्रकाशन की फ़ाइलें बिल्ट-इन हैं।
mathjax और imgmath	HTML के गणित में MathJax इस्तेमाल होता है। PDF समर्थित LaTeX उपसमुच्चय को Typst में बदलता है।
myst_parser	लागू परियोजना Markdown परत।
doctest निर्देश	सामग्री दिखाई जाती है। परियोजना बिल्डर इनके टेस्ट नहीं चलाता।
autodoc	पैकेज इम्पोर्ट या चलाए बिना Python स्रोत पढ़ा जाता है।

स्रोत आधारित autodoc रनटाइम पर बने हर ऑब्जेक्ट को नहीं खोज सकता। कम्पाइल किए मॉड्यूल, बाहरी डेकोरेटर, गणना वाले मान और एक्सटेंशन इवेंट हुक की स्पष्ट सीमाएँ हैं। Python 3.13 और निश्चित Sphinx documenter टेस्ट संदर्भ व्यवहार देते हैं। पूरे विकल्प और अपवाद autodoc से Python का दस्तावेज़ीकरण में हैं।

autosummary, napoleon, viewcode और मनमाने Python एक्सटेंशन इस रास्ते से बाहर हैं। कॉन्फ़िगरेशन में असमर्थित एक्सटेंशन की सूचना मिलती है। अज्ञात निर्देश या रोल स्रोत स्थान पर बताया जाता है। छोड़ी गई सामग्री प्रकाशन से पहले जाँचना ज़रूरी है। अन्य थीम नाम स्वीकार होते हैं, लेकिन Guidedog का थीम कार्यान्वयन इस्तेमाल होता है।

विश्वास और संसाधन सीमाएँ

सामान्य बिल्ड परियोजना का raw HTML और Typst, टेम्पलेट और नेटवर्क इन्वेंटरी स्वीकार करती है। स्थानीय पढ़ाई स्रोत निर्देशिका और स्पष्ट साझा रूट तक सीमित है। प्रतीकात्मक लिंक इस सीमा को नहीं बढ़ाता। टेम्पलेट, स्थिर फ़ाइलें, include, चित्र, फ़ॉन्ट और API स्रोत यही नियम मानते हैं।

Graphviz के चित्र संसाधन दस्तावेज़ के सापेक्ष खोजे जाते हैं और सीमा में रहते हैं। समर्थित चित्र डेटा आरेख में समाहित होता है। imagepath और fontpath सीमा नहीं बढ़ाते। Typst पढ़ने योग्य निर्देशिकाओं वाला निजी रूट इस्तेमाल करता है। इससे किताब के टेम्पलेट और प्रीऐम्बल घोषित संसाधनों तक सीमित रहते हैं।

--untrusted पढ़ने की सीमा स्रोत फ़ोल्डर तक रखता है। raw सामग्री, असुरक्षित URL, बाहरी संसाधन, परियोजना के Typst टेम्पलेट और प्रीऐम्बल निदान के साथ छोड़े जाते हैं। इन्वेंटरी या Typst पैकेज नहीं लाए जाते। संसाधन पढ़ने वाले ग्राफ़ चेतावनी के साथ कोड में दिखते हैं। यह मोड नेटिव कम्पाइलर की मेमोरी या चलने का समय सीमित नहीं करता।

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

--memory=ram प्रबंधित बजट पर रुकता है। --memory=disk प्रबंधित कार्य स्टोरेज को मेमोरी-मैप की गई अस्थायी फ़ाइलें इस्तेमाल करने देता है। सहेजा होस्ट स्टोरेज RAM बजट में गिना जाता है। --disk-budget मैप स्टोरेज सीमित करता है; नीति डिस्क में आरक्षित जगह भी छोड़ती है। गैर-इंटरैक्टिव कमांड उत्तर की प्रतीक्षा नहीं करता। ज्ञात उपलब्ध क्षमता GUIDEDOG_AVAILABLE_MIB से दी जा सकती है।

--max-depth, --max-nodes और --stack-kib दस्तावेज़ के काम को सीमित करते हैं। सीमा बदलने पर पढ़ाई और आउटपुट कैश अमान्य होते हैं। गहराई और स्टैक क्षमता मेल खानी चाहिए। नेटिव Graphviz, tree-sitter और Typst आवंटन होस्ट बजट से बाहर हैं। कठोर सीमा के लिए ऑपरेटिंग सिस्टम की सीमाएँ इस्तेमाल करें। त्रुटि संदेश और मेमोरी और स्वामित्व देखें।

सत्यापन और वास्तविक परियोजनाएँ

tools/sphinxdiff निश्चित Sphinx टेस्ट रूटों में 42 की तुलना करता है। यह पृष्ठ, पहचानकर्ता, मुख्य पाठ के लिंक, इन्वेंटरी, क्रमांकन और निदान जाँचता है। सहेजे परिणाम और README जानबूझकर रखे अंतर समझाते हैं। उदाहरण हैं: सटीक स्रोत स्थान, स्थिर पढ़ने के क्रम में क्रमांकन और छोड़ी गई लक्ष्य-विशिष्ट raw सामग्री की स्पष्ट सूचना।

1 अक्टूबर 2026 के दूरस्थ सत्यापन में CPython, Django और Flask के HTML तथा PDF की नई और अपरिवर्तित बिल्ड चलीं। सभी बारह बिल्ड सफल रहीं और निदान तथा लिंक के परिणाम आधाररेखा से मेल खाए। साथ ही 1,039 Linux टेस्ट और 94 लक्षित AddressSanitizer टेस्ट पास हुए।

इन परियोजनाओं में असमर्थित Python एक्सटेंशन संरचनाएँ हैं। उनके निदान प्रमाण का हिस्सा बने रहते हैं। शून्य एग्ज़िट स्टेटस यह नहीं बताता कि सभी निजी निर्देश दोहराए गए हैं। प्रकाशन में कोई निदान न चाहिए तो -W चलाएँ।

पुराने माप और स्रोत संस्करण docs/manual/evidence/manuals.md में हैं। नवीनतम दूरस्थ समीक्षा build/review-remote-20261001/report.txt में है। ये माप दर्ज काम का वर्णन करते हैं, सार्वभौमिक गति या मेमोरी सीमा का नहीं।