autodoc से Python का दस्तावेज़ीकरण¶
Guidedog सोर्स कोड पढ़कर Python का दस्तावेज़ीकरण करता है। वह पैकेज को import नहीं करता। docstring और signature दस्तावेज़ के ग्राफ़ में शामिल होते हैं। केवल रनटाइम पर बनने वाले ऑब्जेक्ट का विवरण अलग से लिखना पड़ता है। यह सीमा जानबूझकर रखी गई है।
सेटअप¶
एक्सटेंशन बताएँ और Guidedog को सोर्स फ़ोल्डर के सापेक्ष पैकेजों का स्थान दें, जैसे sys.path Python को बताता है:
extensions = ["sphinx.ext.autodoc"]
autodoc_source_paths = ["../src"]
guidedog migrate आपके लिए autodoc_source_paths लिखता है। इसके लिए वह conf.py में पैकेज तक पहुँचने वाली पंक्तियाँ पढ़ता है, जैसे sys.path.insert(0, os.path.abspath('..'))। कहीं और इंस्टॉल किए गए पैकेज के लिए उसका फ़ोल्डर जोड़ना होगा, मसलन किसी dependency का सोर्स checkout। Guidedog कभी Python के अपने site-packages में नहीं खोजता।
इसके बाद directives Sphinx की तरह काम करते हैं:
.. automodule:: shop.cart
:members:
:show-inheritance:
.. autoclass:: shop.Cart
:members: add, remove
:inherited-members:
Sphinx 9.1 के सभी विकल्प उसी अर्थ में स्वीकार किए जाते हैं: :members:, :undoc-members:, :private-members:, :special-members:, :inherited-members:, :exclude-members:, :member-order:, :show-inheritance:, :imported-members:, :ignore-module-all:, :class-doc-from:, :no-value:, :annotation:, :no-index:, :no-index-entry:, :synopsis:, :platform:, :deprecated: और autodoc_default_options को रद्द करने वाले no- रूप।
सेटिंग्स¶
इन conf.toml सेटिंग्स के नाम, मान और डिफ़ॉल्ट Sphinx जैसे ही हैं।
autodoc_source_paths-
यह Guidedog का अपना विकल्प है। Python मॉड्यूल खोजने वाली निर्देशिकाएँ खोज के क्रम में दें। पथ स्रोत निर्देशिका के सापेक्ष हैं। केवल इन निर्देशिकाओं की फ़ाइलें पढ़ी जाती हैं। बाहर जाने वाले प्रतीकात्मक लिंक स्वीकार नहीं होते।
autoclass_content-
क्लास का वर्णन किस docstring से हो:
"class"(डिफ़ॉल्ट),"init"या"both"। autodoc_class_signature-
"mixed"(डिफ़ॉल्ट) या"separated"। दूसरा विकल्प__init__को एक मेथड के रूप में दिखाता है। autodoc_default_options-
हर निर्देश को मिलने वाले विकल्पों की तालिका, जैसे
members = trueयाmember-order = "bysource"।falseदेने पर वह विकल्प छोड़ दिया जाता है। autodoc_docstring_signature-
true(डिफ़ॉल्ट): docstring की पहली पंक्तिname(args) -> resultजैसी हो तो उसे सिग्नेचर माना जाता है। autodoc_inherit_docstrings-
true(डिफ़ॉल्ट): अपना docstring न होने पर सदस्य बेस क्लास का docstring लेता है। autodoc_member_order-
"alphabetical"(डिफ़ॉल्ट),"groupwise"या"bysource"। autodoc_preserve_defaults-
false(डिफ़ॉल्ट): डिफ़ॉल्ट मानrepr()के रूप में दिखते हैं।trueदेने पर स्रोत में लिखा रूप दिखता है। autodoc_typehints-
"signature"(डिफ़ॉल्ट),"description"(:type:और:rtype:फ़ील्ड में),"both"या"none"। autodoc_typehints_description_target-
"all"(डिफ़ॉल्ट),"documented"या"documented_params"। autodoc_typehints_format-
"short"(डिफ़ॉल्ट) या"fully-qualified"। autodoc_use_type_comments-
true(डिफ़ॉल्ट):# type:टिप्पणियाँ टाइप एनोटेशन मानी जाती हैं। strip_signature_backslash-
Sphinx की तरह सिग्नेचर में बैकस्लैश दोहरे किए जाते हैं।
autodoc_mock_imports,autodoc_type_aliases,autodoc_warningiserror-
ये विकल्प स्वीकार होते हैं। कोई मॉड्यूल इम्पोर्ट नहीं किया जाता, इसलिए mock की ज़रूरत नहीं होती। टाइप एलियस लागू नहीं होते।
Guidedog Python के व्यवहार का अनुमान कैसे लगाता है¶
नाम Python के बाइंडिंग नियमों से खोजे जाते हैं। पैकेज के __init__.py में from .app import Flask लिखने से flask.Flask उस क्लास को दर्शाता है जो flask/app.py में परिभाषित है। autodoc इसे :canonical: flask.app.Flask के साथ दिखाता है। बेस क्लास भी इसी तरह खोजी जाती हैं। मेथड रिज़ॉल्यूशन क्रम Python के नियमों से निकलता है और विरासत में मिले सदस्य बेस क्लास के स्रोत से आते हैं। केवल if TYPE_CHECKING: के भीतर इम्पोर्ट किए गए नाम रनटाइम पर मौजूद नहीं होते। इसलिए उन नामों वाले एनोटेशन, Sphinx की तरह, लिखे हुए रूप में रहते हैं।
docstring वही स्ट्रिंग होती है जिसे Python संग्रहीत करता। एस्केप प्रोसेस होते हैं और इंडेंटेशन Python 3.13 कम्पाइलर के नियमों से हटता है। एट्रिब्यूट का वर्णन Sphinx के विश्लेषक वाली जगहों से मिलता है: असाइनमेंट के बाद या ठीक ऊपर की #: टिप्पणी और उसके ठीक बाद का स्ट्रिंग लिटरल। सिग्नेचर def से मिलता है। क्लास के लिए Python के खोज क्रम में मेटाक्लास का __call__, __new__ या __init__ लिया जाता है। dataclass और NamedTuple के लिए फ़ील्ड काम आते हैं। @overload के रूप कार्यान्वयन के सिग्नेचर की जगह लेते हैं।
Python चलाए बिना क्या नहीं जाना जा सकता¶
जब स्रोत से Python का व्यवहार पता नहीं चल सकता, Guidedog संबंधित ऑब्जेक्ट का नाम लेकर बताता है। दस्तावेज़ बनाना संभव न हो तो चेतावनी देता है। Sphinx से कम जानकारी के साथ दस्तावेज़ बने तो एक सूचना देता है, जो -v से दिखाई देती है।
- कम्पाइल किए गए मॉड्यूल (
.so,.pyd) का स्रोत उपलब्ध नहीं होता, इसलिए उसके ऑब्जेक्ट नहीं मिलते। - कोड चलाकर बने मान (
app = Flask(__name__),now = datetime.now()) के लिए:value:नहीं मिलता। गणना से मिलने वाला डिफ़ॉल्ट स्रोत के लिखे रूप में दिखता है। - स्रोत पथों के बाहर के डेकोरेटर (
@click.command()) से बनी फ़ंक्शन का वर्णन मूल फ़ंक्शन के आधार पर होता है। - स्रोत पथों के बाहर के पैकेज की क्लास का नाम उसके इम्पोर्ट पथ से दिया जाता है। यह पथ उसे परिभाषित करने वाले मॉड्यूल से अलग हो सकता है। उसके सदस्य, कन्स्ट्रक्टर का सिग्नेचर और आगे विरासत में मिलने वाले docstring अज्ञात रहते हैं।
- बिल्ट-इन टाइप के docstring उपलब्ध नहीं होते। इसलिए अपना docstring न रखने वाला मेथड, जिसे
dictसे मिलना होता, छोड़ दिया जाता है। - autodoc के इवेंट (
autodoc-process-docstring,autodoc-skip-memberआदि) संभालने वाले Python एक्सटेंशन नहीं चलते। - सामान्य कोड से बहुत अधिक नेस्टिंग वाले मॉड्यूल का विश्लेषण नहीं होता और
autodoc.too_deepचेतावनी मिलती है। Python खुद 200 स्तर के नेस्टेड ब्रैकेट अस्वीकार करता है। Guidedog कुछ सौ ऑपरैंड वाली+शृंखला भी अस्वीकार करता है। - बढ़ते जाने वाले काम की सीमाएँ तय हैं। इम्पोर्ट और एलियस से नाम खोजते समय एक पथ पर 48 कदम और कुल 100,000 कदम तक चलते हैं। टाइप एलियस या स्थिरांक 10,000 कदम तक खोले जाते हैं; उसके बाद लिखे हुए रूप में दिखते हैं। क्लास का MRO 100 क्लास तक खोजा जाता है। एक निर्देश अधिकतम 10,000 निर्देश बनाता है; सीमा पार करने पर
autodoc.limitचेतावनी मिलती है। आख़िरी सीमा तक केवल वह क्लास पहुँचती है जो अपने नाम से खुद को समाहित करती है।
अनुपलब्ध पैकेजों की स्रोत निर्देशिकाएँ autodoc_source_paths में जोड़ने से इनमें से अधिकतर सीमाएँ दूर हो जाती हैं।
दोबारा बिल्ड करना¶
autodoc निर्देश की पढ़ी हुई हर Python फ़ाइल पृष्ठ की निर्भरता बनती है। उसे बदलने पर अगली बिल्ड में पृष्ठ फिर पढ़ा जाता है। जिस पृष्ठ का ऑब्जेक्ट नहीं मिला, वह हर बिल्ड में फिर पढ़ा जाता है। स्रोत में ऑब्जेक्ट आते ही वह मिल जाता है।
सुरक्षा¶
दस्तावेज़ बनाते समय परियोजना का कोड कभी नहीं चलता। Guidedog Python स्रोत को पाठ की तरह पढ़ता है और include जैसी पथ सीमा लागू करता है: केवल autodoc_source_paths के भीतर, बाहर जाने वाले लिंक से नहीं।