5

rstを含むファイルで Sphinx を実行していますautomoduleが、効果がないようです。

詳細は次のとおりです。agent.pyクラスを含むファイルを含むPythonプロジェクトがありますAgent。apidocファイルを含むサブディレクトリもありますagent.rst（によって生成されますsphinx-apidoc）：

agent module
============

.. automodule:: agent
   :members:
   :undoc-members:
   :show-inheritance:

sphinx-build -b html apidoc apidoc/_buildプロジェクトのディレクトリを現在の作業ディレクトリとしてsphinx を実行します。

Python ファイルが確実に見つかるように、次のファイルを に含めましたapidoc/conf.py。

import os
import sys
sys.path.insert(0, os.path.abspath('.'))

エラーなしで実行されますが、結果の HTML ファイルを開くと、「エージェント モジュール」しか表示されず、すべてが空白です。Agentクラスとそのメンバーが表示されないのはなぜですか?

更新: 元の問題は、私sphinx.ext.autodocがconf.py. しかし、今では、次のような警告が表示されます。

WARNING: invalid signature for automodule ('My Project.agent')
WARNING: don't know which module to import for autodocumenting 'My Project.agent' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: autodoc: failed to import module 'agent'; the following exception was raised:
No module named 'agent'
4

1 に答える 1

9

「標準的な」アプローチをあなたのケースと並べて答えてみます。

通常の「開始方法」は次の手順に従います。

  1. ディレクトリにディレクトリを作成docしますproject(このディレクトリから、次の手順のコマンドが実行されます)。

  2. sphinx-quickstartsource（とは別に選択build）。

  3. sphinx-apidoc -o ./source ..

  4. make html

これにより、次の構造が生成されます。

C:\Project
|
|   agent.py
|   
|---docs
|   |   make.bat
|   |   Makefile
|   |   
|   |---build
|   |               
|   |---source
|       |   conf.py
|       |   agent.rst
|       |   index.rst
|       |   modules.rst

あなたconf.pyが追加したい（ステップ2の後）：

sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))

そして、index.rstあなたはリンクしますmodules.rst：

Welcome to Project's documentation!
================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules


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

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

上記をあなたが持っているものと比較してください-質問で共有したものから:

C:\Project
|
|   agent.py
|   
|---apidoc
|   |   agent.rst
|   |   conf.py
|   |
|   |-- _build

あなたが走った： sphinx-build -b html apidoc apidoc/_build

そしてあなたのconf.py：

sys.path.insert(0, os.path.abspath('.'))

エラースタックトレースは、モジュールが見つからなかったと言っていますagent。これはおそらく、 で 1 レベル下に移動しなかったためです( のパスではなく、conf.pyのパスを指しています) 。また、手動で編集/接続しなかった場合、そのモジュールのみが表示される可能性があります 。.rst.pysys.path.insert(0, os.path.abspath('..'))modules.rstindex.rst
プレイ中のスフィンクス コマンドのシグネチャに注目してください。

sphinx-apidoc [OPTIONS] -o <OUTPUT_PATH> <MODULE_PATH>

sphinx-build [options] <sourcedir> <outputdir> [filenames …]

<sourcedir>.rstどこにいるのか、どこにいるの<MODULE_PATH>かを指し.pyます。<OUTPUT_PATH>どこ.rstに置くか、<outputdir>どこ.htmlに置くか。

また、「現在の作業ディレクトリとしてのプロジェクトのディレクトリ」と述べたことにも注意してください。stackoverflow の sphinx スレッドで言及されている「作業ディレクトリ」を見たことがあります。これは、Project基本ディレクトリまたはディレクトリの両方として互換性がありdocsます。ただし、Sphinx のドキュメントで「作業ディレクトリ」を検索しても、それに関する言及は見つかりません。

最後に、「入門アプローチ」のファイル/ディレクトリ構造を使用する利点があります。基本的に、Sphinx タグのほとんどのスレッドと「同じページに移動」し、そのようにして、ケースを異なるディレクトリ/ファイル構造にマッピングするという精神的な作業を軽減します。

これが役立つことを願っています。

于 2020-01-28T15:08:41.480 に答える