توليد وثائق تلقائيًا لجميع محتويات حزمة Python

Question

أحاول أن أقوم بتوثيق الوثائق الأساسية لاستخدام قاعدة قاعدة الشفرة الخاصة بي باستخدام sphinx. ومع ذلك ، أواجه صعوبة في توجيه SPHINX لمسح ملفاتي بشكل متكرر.

لدي قاعدة كود بيثون مع بنية مجلد مثل:

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

ركضت sphinx-Quickstart في <workspace>, ، والآن يشبه هيكلتي:

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

لقد قرأت البرنامج التعليمي QuickStart http://sphinx.pocoo.org/tutorial.html, ، وعلى الرغم من أنني ما زلت أحاول فهم المستندات ، فإن الطريقة التي يتم بها صياغتها تجعلني أشعر بالقلق من أن Sphinx يفترض أنني سأقوم بإنشاء ملفات توثيق يدويًا لكل وحدة/فئة/وظيفة واحدة في قاعدة الكود الخاصة بي.

ومع ذلك ، لاحظت عبارة "Automodule" ، وقمت بتمكين AutoDOC أثناء التشغيل السريع ، لذلك آمل أن يتم إنشاء معظم الوثائق تلقائيًا. لقد قمت بتعديل Conf.py لإضافة مجلد SRC الخاص بي إلى Sys.Path ثم قمت بتعديل الفهرس الخاص بي لاستخدام السيارات. لذا الآن يشبه الفهرس الخاص بي:

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

ويبدو أن هذا فشل في استيراد أي شيء داخل الحزمة الخاصة بي. عرض الفهرس الذي تم إنشاؤه. html لا يعرض شيئًا بجوار "المحتويات:". تُظهر صفحة الفهرس فقط "myPackage (الوحدة النمطية)" ، ولكن النقر فوقه يوضح أنه لا يحتوي أيضًا على محتويات.

كيف يمكنك توجيه sphinx لتحليل الحزمة بشكل متكرر وإنشاء وثائق لكل فئة/طريقة/وظيفة تواجهها ، دون الحاجة إلى سرد كل فئة يدويًا بنفسك؟

Answer 1

ربما يمكن أن يساعد apigen.py: https://github.com/nipy/nipy/tree/master/tools.

تم وصف هذه الأداة بإيجاز هنا: http://comments.gmane.org/gmane.comp.python.sphinx.devel/2912.

أو الأفضل من ذلك ، استخدم PDOC.

---

تحديث: sphinx-apidoc تمت إضافة الأداة المساعدة في أبو الهول الإصدار 1.1.

Answer 2

يمكنك محاولة استخدام sphinx-apidoc.

$ 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>.

يمكنك مزج sphinx-apidoc مع sphinx-QuickStart من أجل إنشاء مشروع DOC بالكامل مثل هذا:

$ sphinx-apidoc -F -o docs project

ستنشئ هذه المكالمة مشروعًا كاملاً مع sphinx-QuickStart وتبدو بشكل متكرر في (Project) لوحدات Python.

أتمنى أن يساعدك هذا!

Answer 3

ملحوظة

بالنسبة لـ sphinx (في الواقع ، مترجم Python الذي ينفذ sphinx) للعثور على الوحدة النمطية الخاصة بك ، يجب أن يكون قابلاً للاستيراد. هذا يعني أن الوحدة النمطية أو الحزمة يجب أن تكون في إحدى الدلائل على Sys.Path - تكييف SYS.Path الخاص بك في ملف التكوين وفقاً لذلك

لذا ، انتقل إلى conf.py وأضف

import an_example_pypi_project.useful_1
import an_example_pypi_project.useful_2

الآن يشبه الفهرس الخاص بك:

.. toctree::
   :glob:

   example
   an_example_pypi_project/*

و

make html