Sphinx autodocは十分に自動化されていません


149

Sphinxを使用して5,000行以上のプロジェクトをPythonでドキュメント化しようとしています。約7つの基本モジュールがあります。私の知る限り、autodocを使用するには、プロジェクト内の各ファイルに対して次のようなコードを記述する必要があります。

.. automodule:: mods.set.tests
    :members:
    :show-inheritance:

多くのファイルを持っているので、これは非常に面倒です。「mods」パッケージを文書化することを指定できれば、はるかに簡単になります。Sphinxはパッケージを再帰的に調べ、各サブモジュールのページを作成します。

このような機能はありますか?そうでない場合、すべての.rstファイルを作成するスクリプトを作成できますが、これには多くの時間がかかります。


「os.walk」を使用してこれをすべて記述する小さなスクリプトの作成の何が問題になっていますか?ところで、私は40,000以上のラインプロジェクトを持っているので、あなたが何を話しているのか分かりません。いくつのファイルが関係していますか?lsファイルにルーティングして編集するのはどれほど難しいですか?
S.Lott、2010

124
難しいと言った人はいません。OPは、それが退屈であると述べた。他のdocシステムがこれを行うことができることを考えると、それは不合理ではありません。
グレッグリンド

pdocを使用するだけです。
K3 --- rnc

回答:


143

私が作成したこのスクリプトを確認できます。それはあなたを助けることができると思います。

このスクリプトは、Pythonモジュールとパッケージを探すディレクトリツリーを解析し、Rehinファイルを適切に作成して、Sphinxでコードドキュメントを作成します。また、モジュールインデックスを作成します。

更新

このスクリプトはapidocとしてSphinx 1.1の一部になりました


ファイルの出力先はどこですか?Sphinxのデフォルトの_buildフォルダーに出力してみましたが、実行sphinx-build -b html . ./_buildしても取得されません。
セリン

あなたはそれらをsource directory(あなたの場合。)に入れるべきです。_buildディレクトリは、HTMLファイルが作成される場所です。詳細を確認してください:sphinx.pocoo.org/tutorial.html#running-the-build
エティエンヌ

1
@エリエンヌ:素晴らしいスクリプト!ちょうど私が探していたもの。個々のクラスの見出しを生成したいと思います(通常のスフィンクスの外観はクラスにはよくありません。それらは大きなモジュールで失われます)
適さ jbenet

1
sphinx-apidocもかなり初歩的です。1つまたは2つのモジュールを含むパッケージの場合、問題なく動作しますが、モジュールが深くネストされており、sphinx-apidocはかなり扱いにくい出力を生成します。
滑らかな

4
自己回答:.. include:: modules.rstあなたに追加index.rst
Ciro Santilli郝海东冠状病六四事件法轮功

39

autosummary元の質問が尋ねられたときにSphinxが拡張機能を持っていたかどうかはわかりませんが、現時点ではsphinx-apidoc、類似のスクリプトを使用せずに、そのような自動生成を設定することは十分に可能です。以下に、私のプロジェクトの1つで機能する設定があります。

  1. autosummary拡張機能を有効にする(およびautodoc)をするconf.pyファイルのおよび、そのautosummary_generateオプションをに設定しますTrue。カスタム*.rstテンプレートを使用していない場合は、これで十分です。それ以外の場合は、テンプレートディレクトリを除外リストに追加するか、テンプレートautosummaryを入力ファイルとして扱います(バグのようです)。

    extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary']
    autosummary_generate = True
    templates_path = [ '_templates' ]
    exclude_patterns = ['_build', '_templates']
  2. 使用する autosummary::目次ツリーでindex.rstファイルのます。モジュールについては、この例のドキュメントではproject.module1project.module2自動的に生成され、中に置か_autosummaryディレクトリ。

    PROJECT
    =======
    
    .. toctree::
    
    .. autosummary::
       :toctree: _autosummary
    
       project.module1
       project.module2
  3. デフォルトでは autosummaryは、モジュールとその機能の非常に短い要約のみが生成されます。これを変更するには、カスタムテンプレートファイルを_templates/autosummary/module.rstJinja2で解析される)に配置します。

    {{ fullname }}
    {{ underline }}
    
    .. automodule:: {{ fullname }}
        :members:

結論として、維持する必要はありません _autosummaryディレクトリをバージョン管理下。また、任意の名前を付けて、ソースツリーの任意の場所に配置できます(_buildただし、下に配置しても機能しません)。


4
これは大きな助けとなりました。「project.module1」と「project.module2」があるポイント2で、特定のパッケージ内のすべてのモジュールに対してそのリストを自動的に生成する方法はありますか?「プロジェクト」を配置して「モジュール1」と「モジュール2」を嗅ぎ取るには?
ブラウン

これに対する答えがどこにも見つからないことにかなり驚いています。@ Brownで解決したことはありますか?
Alisdair Robertson 2017

3
@AlisdairRobertsonいいえ。ただし、提供された自動集計ソリューションは、私のニーズに対して十分以上のものでした。他に考えたのは、index.rstファイルを生成してモジュール名を自動検出するスクリプトを記述することだけでした。ただし、実際には、モジュールのリストはそれほど頻繁に変更されないため、たまに1つのファイルを編集するだけでは不合理ではありません。私はすでに、1つのファイルを編集するだけではなく、解決策を探すのにずっと多くの時間を費やしていると確信しています!
ブラウン

12

各パッケージで、 __init__.pyファイルに.. automodule:: package.module各部分のコンポーネントを含めることができます。

そうすればできる.. automodule:: packageし、たいていはあなたがやりたいことをする。


その文字列をinit .pyの三重引用符で囲むだけですか?
Cory Walker

5
@Cory Walker:「a」文字列ではありません。あなたはできます-そしてすべきです -すべての単一のファイルにトリプル引用されたドキュメンテーション文字列を置くこと。全員。これには、__init__.pyパッケージ内のファイルが含まれます。docstringには.. automodule::、パッケージ内のモジュールを含む、任意のSphinxドキュメントディレクティブを含めることができます。
S.Lott

2
autodoc 誤植です。 automoduleです。ヒントをたくさんありがとう!
mariotomo

9

Sphinxバージョン3.1(2020年6月)以降、sphinx.ext.autosummary(ついに!)再帰があります。

したがって、モジュール名をハードコードしたり、Sphinx AutoAPISphinx AutoPackageSummaryなどのサードパーティライブラリに依存したりする必要はありません。て自動パッケージを検出し。

ドキュメント化するPython 3.7パッケージの例(GithubのコードReadTheDocsの結果を参照):

mytoolbox
|-- mypackage
|   |-- __init__.py
|   |-- foo.py
|   |-- mysubpackage
|       |-- __init__.py
|       |-- bar.py
|-- doc
|   |-- source
|       |--index.rst
|       |--conf.py
|       |-- _templates
|           |-- custom-module-template.rst
|           |-- custom-class-template.rst

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))  # Source code dir relative to this file

extensions = [
    'sphinx.ext.autodoc',  # Core library for html generation from docstrings
    'sphinx.ext.autosummary',  # Create neat summary tables
]
autosummary_generate = True  # Turn on sphinx.ext.autosummary

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

index.rst(新しい:recursive:オプションに注意してください):

Welcome to My Toolbox
=====================

Some words.

.. autosummary::
   :toctree: _autosummary
   :template: custom-module-template.rst
   :recursive:

   mypackage

これは、パッケージ内のすべてのモジュールを自動的に要約するには十分ですが、深くネストされています。次に、各モジュールについて、そのモジュール内のすべての属性、関数、クラス、および例外を要約します。

奇妙なことに、デフォルトは sphinx.ext.autosummaryテンプレートでは、属性、関数、クラス、および例外ごとに個別のドキュメントページが生成されず、サマリーテーブルからリンクされます。以下に示すように、これを行うためにテンプレートを拡張することは可能ですが、これがデフォルトの動作ではない理由を理解できません-確かに、ほとんどの人はそれを望んでいます。私はそれを機能要求として上げました

デフォルトのテンプレートをローカルにコピーしてから、それらに追加する必要がありました。

  • コピーする site-packages/sphinx/ext/autosummary/templates/autosummary/module.rstmytoolbox/doc/source/_templates/custom-module-template.rst
  • コピーする site-packages/sphinx/ext/autosummary/templates/autosummary/class.rstmytoolbox/doc/source/_templates/custom-class-template.rst

へのフックcustom-module-template.rstindex.rst:template:オプションを使用して上にます。(その行を削除して、デフォルトのサイトパッケージテンプレートを使用して何が起こるかを確認してください。)

custom-module-template.rst (右側に記載されている追加の行):

{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}
  
   {% block attributes %}
   {% if attributes %}
   .. rubric:: Module Attributes

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in attributes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block functions %}
   {% if functions %}
   .. rubric:: {{ _('Functions') }}

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in functions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block classes %}
   {% if classes %}
   .. rubric:: {{ _('Classes') }}

   .. autosummary::
      :toctree:                                          <-- add this line
      :template: custom-class-template.rst               <-- add this line
   {% for item in classes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block exceptions %}
   {% if exceptions %}
   .. rubric:: {{ _('Exceptions') }}

   .. autosummary::
      :toctree:                                          <-- add this line
   {% for item in exceptions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

{% block modules %}
{% if modules %}
.. rubric:: Modules

.. autosummary::
   :toctree:
   :template: custom-module-template.rst                 <-- add this line
   :recursive:
{% for item in modules %}
   {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

custom-class-template.rst (右側に記載されている追加の行):

{{ fullname | escape | underline}}

.. currentmodule:: {{ module }}

.. autoclass:: {{ objname }}
   :members:                                    <-- add at least this line
   :show-inheritance:                           <-- plus I want to show inheritance...
   :inherited-members:                          <-- ...and inherited members too

   {% block methods %}
   .. automethod:: __init__

   {% if methods %}
   .. rubric:: {{ _('Methods') }}

   .. autosummary::
   {% for item in methods %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: {{ _('Attributes') }}

   .. autosummary::
   {% for item in attributes %}
      ~{{ name }}.{{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

6

Sphinx AutoAPIはまさにこれを行います。


1
おやまあー!これは他の何よりもはるかにうまく機能します。これは「autodoc」や「apidoc」ではなく、完全に異なる拡張機能であることに注意してください。
ロープラダー

2
同上。このプット「autodocの」中「自動」....ここでは、すべての私たちのプロジェクトは、スイッチにしなければならなかったです:nealmcbによってautodocのからautoapiへのスイッチ・プル要求\#7・gwexploratoryaudits / r2b2
nealmcb

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.