सभी पायथन पैकेज सामग्री के लिए स्वचालित रूप से जनरेटिंग जनरेटिंग

Question

मैं स्फिंक्स का उपयोग करके अपने कोडबेस के लिए मूल दस्तावेज़ीकरण को स्वत: उत्पन्न करने का प्रयास कर रहा हूं। हालांकि, मुझे अपनी फ़ाइलों को दोबारा स्कैन करने के लिए स्फिंक्स को निर्देश देने में कठिनाई हो रही है।

मैं की तरह एक फ़ोल्डर संरचना के साथ एक अजगर codebase है:

<workspace> 
    src 
     mypackage 
      __init__.py 
      subpackageA 
       __init__.py 
       submoduleA1 
       submoduleA2 
      subpackageB 
       __init__.py 
       submoduleB1 
       submoduleB2 

मैं <workspace> में स्फिंक्स-त्वरित प्रारंभ भाग गया, तो अब मेरी संरचना की तरह दिखता है:

<workspace> 
    src 
     mypackage 
      __init__.py 
      subpackageA 
       __init__.py 
       submoduleA1 
       submoduleA2 
      subpackageB 
       __init__.py 
       submoduleB1 
       submoduleB2 
    index.rst 
    _build 
    _static 
    _templates 

मैं त्वरित प्रारंभ पढ़ा है ट्यूटोरियल http://sphinx.pocoo.org/tutorial.html, और हालांकि मैं अभी भी दस्तावेज़ों को समझने की कोशिश कर रहा हूं, जिस तरह से यह शब्द है, मुझे चिंतित करता है कि स्फिंक्स मानता है कि मैं अपने कोडबेस में प्रत्येक मॉड्यूल/कक्षा/फ़ंक्शन के लिए मैन्युअल रूप से दस्तावेज़ फ़ाइलों को बनाने जा रहा हूं।

हालांकि, मैंने "ऑटोमॉड्यूल" कथन नोटिस किया, और मैंने क्विकस्टार्ट के दौरान ऑटोडोक सक्षम किया, इसलिए मुझे उम्मीद है कि अधिकांश दस्तावेज स्वचालित रूप से जेनरेट किए जा सकते हैं। मैंने sys.path में अपना src फ़ोल्डर जोड़ने के लिए अपना conf.py संशोधित किया और फिर ऑटो्यूल्यूल का उपयोग करने के लिए मेरी index.rst को संशोधित किया। तो अब मेरा index.rst इस तरह दिखता है:

Contents: 

.. toctree:: 
    :maxdepth: 2 

Indices and tables 
================== 

* :ref:`genindex` 
* :ref:`modindex` 
* :ref:`search` 

.. automodule:: alphabuyer 
    :members: 

मेरे पास उप-पैकेज में परिभाषित दर्जनों वर्ग और कार्य हैं। फिर भी, जब मैं चलाएँ:

sphinx-build -b html . ./_build 

यह रिपोर्ट:

updating environment: 1 added, 0 changed, 0 removed 

और ये मेरे पैकेज के अंदर कुछ भी आयात करने में विफल हो गया था। जेनरेट किए गए index.html को देखकर "सामग्री:" के बगल में कुछ भी नहीं दिखाता है। इंडेक्स पेज केवल "मायपैकेज (मॉड्यूल)" दिखाता है, लेकिन इसे क्लिक करने से पता चलता है कि इसमें कोई सामग्री नहीं है।

आप स्फिंक्स को फिर से एक पैकेज का विश्लेषण करने के लिए कैसे निर्देशित करते हैं और प्रत्येक वर्ग/विधि/फ़ंक्शन के लिए स्वचालित रूप से दस्तावेज जेनरेट करते हैं, बिना प्रत्येक वर्ग को मैन्युअल रूप से सूचीबद्ध किए बिना?

Answer 1

शायद apigen.py मदद कर सकता है: https://github.com/nipy/nipy/tree/master/tools।

यह टूल यहां बहुत संक्षेप में वर्णित है: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912।

---

अद्यतन: sphinx-apidoc उपयोगिता स्फिंक्स version 1.1 में जोड़ा गया है।

Answer 2

आप स्फिंक्स-एपिडोक का उपयोग करने का प्रयास कर सकते हैं।

$ sphinx-apidoc -F -o docs project 

इस कॉल स्फिंक्स-त्वरित प्रारंभ के साथ एक पूर्ण परियोजना पैदा करते हैं और में रिकर्सिवली दिखेगा:

$ sphinx-apidoc --help 
Usage: sphinx-apidoc [options] -o <output_path> <module_path> [exclude_paths, ...] 

Look recursively in <module_path> for Python modules and packages and create 
one reST file with automodule directives per package in the <output_path>. 

आपको इस तरह पूरे दस्तावेज़ प्रोजेक्ट बनाने के लिए में स्फिंक्स-त्वरित प्रारंभ साथ स्फिंक्स-apidoc मिश्रण कर सकते हैं (परियोजना) पायथन मॉड्यूल के लिए।

आशा है कि इससे मदद मिलती है!

Answer 3

नोट

स्फिंक्स (वास्तव में, पायथन दुभाषिया कि स्फिंक्स कार्यान्वित) अपने मॉड्यूल को खोजने के लिए के लिए यह आयात योग्य होना चाहिए। इसका मतलब है कि मॉड्यूल या पैकेज sys.path पर निर्देशिका में से एक में होना चाहिए - विन्यास फाइल में अपने sys.path अनुकूलन तदनुसार

तो, अपने conf.py करने के लिए जाना और जोड़ने

import an_example_pypi_project.useful_1 
import an_example_pypi_project.useful_2 

अब आप अपने index.rst लगता है:

.. toctree:: 
    :glob: 

    example 
    an_example_pypi_project/* 

और

make html