मैंने कई companies में Sphinx documentation संभाली है, कुल मिलाकर 100 से अधिक अलग services के लिए. Sphinx documentation site वर्षों से मेरी desk reference है, और TechWriters.ru भी अगस्त 2026 तक इसी engine पर चला. toctree, include, roles, domains, themes और build warnings का अनुभव production projects से है.
अनुभव topic समझाता है, score तय नहीं करता. Portal और repository को onboarding, structure, reference, examples, reuse, build, search, versions, interface और translation के आधार पर जाँचा गया.
Research में क्या देखा गया
Snapshot 17 अगस्त 2026 का है. Public master site और official repository के doc/ tree को commit e44a40e पर देखा गया. Counts source से और editorial findings rendered pages से आए.
.rst files release history सहित
changes/ के बाहर .rst files
wc -w से words और tokens
enabled built-in extensions
documented builder types
Compact source project बहुत बड़े product को cover करता है
Corpus onboarding, user guide, extension development, Sphinx API, commands, configuration, formats, FAQ और पूरी release history तक जाता है.
| Need | Section | Reader result |
|---|---|---|
| शुरुआत | Getting started और full tutorial | Short orientation और narrative plus API वाला guided project. [S2] |
| इस्तेमाल | reStructuredText, Markdown, links, configuration, builders, domains | Markup से internationalization तक पूरा manual. [S3] |
| Extension | Tutorials, how-tos और API | Roles, directives, events, domains, parsers, themes और tests. [G3] |
| Maintenance | Community, contribution, releases और FAQ | Project operation और cleanup माँगते पुराने answers. [S11] |
| Reference | Commands, conf.py, extensions, glossary, changelog | इस आकार के project के लिए असाधारण depth. [S1] |
Developers Sphinx को Sphinx का test bench बनाते हैं
Configuration और source लगभग पूरा characteristic feature set दिखाते हैं.
Structure
[G3]35 toctree documents जोड़ते हैं और home page चार content groups बनाता है.
Reuse
[S4]Normal include और 31 literalinclude real Python files पढ़ते हैं.
Code से API
[G2]autodoc और autosummary enabled हैं, साथ में 13 automodule, 75 autoclass, 18 autofunction.
Cross-project
[S9]intersphinx Python, Requests और Read the Docs जोड़ता है.
Diagrams
[G2]Graphviz और inheritance diagrams phases, events और classes दिखाते हैं.
Versions
[S12]612 versionadded, 252 versionchanged और 18 deprecated API के पास हैं.
Formats
[S6]21 builders documented हैं और project HTML, PDF, ePub, man तथा Texinfo तैयार करता है.
Validation
[G2]nitpicky, coverage, warning types और linkcheck build को quality check बनाते हैं.
Reuse reStructuredText से प्रेम करने का बड़ा कारण है
एक shared section कई guides में आ सकता है, markers से सीमित हो सकता है और builder के अनुसार बदल सकता है. literalinclude, only, rst_prolog और rst_epilog इसी model को बढ़ाते हैं.
include
Shared .rst fragment या marked section insert करता है.
literalinclude
Real file से code पढ़कर drift घटाता है.
only
Builder या tag के अनुसार content बदलता है.
rst_prolog और rst_epilog
Global definitions और inclusions जोड़ते हैं.
एक section, दो guides
.. include:: _shared/security-note.rst
:start-after: .. security-start
:end-before: .. security-end_shared/security-note.rst single source रहता है और दोनों pages को एक ही correction मिलता है.
Editorial score: 78/100
Reference, reuse और engineering को full marks मिलते हैं. Interface और translation result घटाते हैं.
78/100
Reader journey सही है, लेकिन दो बार शुरू होती है
Home page onboarding, guide, community और reference अच्छी तरह अलग करता है. Getting started और Build your first project कुछ आधार दोहराते हैं और fast route तथा full tutorial को पर्याप्त स्पष्टता से अलग नहीं करते.
| Observation | Evidence | Editorial view |
|---|---|---|
| Strong map | चार groups content type साफ करते हैं. | Architecture तुरंत समझ आती है. [S1] |
| Practical tutorial | Fictional library narrative और API जोड़ती है. | Continuous example बेहतर सिखाता है. [S2] |
| Two entries | Foundations आंशिक रूप से repeat होते हैं. | Fast route और full tutorial नाम से अलग करें. [S1] |
| Unfinished end | Quickstart More topics to be covered पर खत्म होता है. | Draft residue model page को कमजोर करता है. [S1] |
| Uneven editing | Home page पर Add documentation translations multiple languages बचा है. | Showcase पर grammar gap स्पष्ट है. [S1] |
| Old FAQ | Epydoc, SCons, old PyPI hosting और _gaq अभी हैं. | Historical answers current troubleshooting से अलग हों. [S11] |
Interface project की उम्र दिखाता है
Navigation, search, index, source और versions काम करते हैं. sphinx13 theme dense है और dark Read the Docs panel अलग application जैसा लगता है.
काम करता है
Tree, anchors, index, search, source और versions.
पुराना लगता है
Dense typography, छोटे links, crowded sidebar और अलग RTD panel.
भ्रमित करता है
Russian, German और French जाँचे गए; कोई complete नहीं है. Russian और German लगभग पूरा English रहते हैं, French translation के बीच English paragraphs रखता है.
पहली priority
Translation coverage दिखाएँ और deep navigation बचाते हुए theme update करें.
अपनाने योग्य practices
| Practice | Adopt |
|---|---|
| Semantic links | Objects और sections को identifier से reference करें. |
| Shared fragments | Warnings और requirements include से reuse करें. |
| Live examples | Tested code literalinclude से पढ़ें. |
| Version notes | Changes और deprecations API के पास रखें. |
| Strict build | Warnings, links और references CI में validate करें. |
| Multiple formats | Same source से PDF, man या ePub बनाएँ. |
| Honest localization | Partial translation को complete language न दिखाएँ. |
Research sources
निष्कर्ष: पुरानी storefront में उत्कृष्ट engineering
Sphinx source level पर खुद को लगभग आदर्श रूप से document करता है और hierarchy, reuse, semantic links, generated API, diagrams तथा multiple outputs इस्तेमाल करता है.
कमजोरी reading experience में है: old interface, duplicate starts, draft residue, historical FAQ और translation coverage को बढ़ा-चढ़ाकर दिखाने वाला menu.
Review के बाद भी Sphinx प्रिय रहता है. Exact structure, reuse और build discipline का ऐसा संयोजन दुर्लभ है.
Sphinx portal engine की शक्ति साबित करता है और दिखाता है कि engineering quality presentation से आगे निकल सकती है.