pythonでdocstringをsphinxでAPIドキュメント化したいがエラー

Question

前提・実現したいこと

pythonでdocstringの記載内容からAPIをドキュメント化したいです。
sphinxでhtml化を試みていますが、エラーが発生しました。

python 3.7.5 + sphinx です。

■フォルダ構成（フォルダ・ファイル名は一部仮です）

+-docs
|  +-conf.py
|  +-index.rst
|  +-modules.rst
+-pkg
   +-source1.py
   +-source2.py

■ファイル
index.rst(抜粋)

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

  source1

conf.py(抜粋)

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

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'sphinxarg.ext',
]

■実行コマンド

> sphinx-quickstart docs
> cd docs
> sphinx-apidoc -f -o ./ ../pkg
> make html

発生している問題・エラーメッセージ

> make html
上記のコマンドの結果、以下のエラーが発生します.

WARNING: autodoc: failed to import module 'source2' from module 'pkg'; the module executes module level statement and it might call sys.exit().

なお、pkgフォルダ配下に複数のソースファイルがありますが、すべてではなく、一部のファイルのみ上記のエラーが発生します。

試したこと

moduleがimportできないとのエラーメッセージから、パスを追加してみました.

sys.path.insert(0, os.path.abspath('./'))
sys.path.insert(0, os.path.abspath('./pkg'))
sys.path.insert(0, os.path.abspath('../pkg'))
sys.path.insert(0, os.path.abspath('fullpath/pkg'))

結果変わらず。

検索したところ、以下を発見しました。
https://stackoverflow.com/questions/34570114/python-sphinx-the-module-executes-module-level-statement-and-it-might-call-sys
まさにargparseを使用しているので該当しそうに思いますが、内容があまり理解できませんでした。
cmd_line_paramsって定義されていないようですし。

どうすればよいのか分からず、困っています。
解消方法について何か分かりましたらご教示いただけますと助かります。

Answer 1

（切り分けの手段として参考にしてください）

エラー内容は「pkgでのsource2のimportに失敗している」と読み取れます。

実行時はmake htmlを実行した場所か、conf.pyがある場所をカレントディレクトリとして動作するはずですので、その場所でpkgをimportするだけの捨てスクリプトを作って動かしてみてください。

これで同じエラーが出ればsphinxなしで調査が進められると思います。

Answer 2

関数やクラス、あるいは望まれた上でのグローバル変数の定義の他に、モジュールのimportで直接実行されてしまう行があるのではないでしょうか。

if __name__ == "__main__":などを駆使して、単にimport source2などとしたときには定義部分だけが走るようにしておいてください。実際にプログラムを実行する処理はimport時には走らないようにする必要があります。

Comments

[palayo]

ご回答ありがとうございます。
ソースを確認したところ、関数定義、グローバル変数の定義のほかに、ロガーの定義があります。
`logger = getLogger(__name__)`

後ほどコメントアウトして実施してみたいと思いますが、
（logger箇所全部コメントにする必要がありますね・・）
imort時に走る処理があるとsphinxでエラーになるということなのでしょうか。

[palayo]

import時に走る処理
```
logger = getLogger(__name__)
```
をコメントアウトし、全logger箇所をコメントアウトしてみたのですが、やはり以下のエラーが発生します。
```
WARNING: autodoc: failed to import module 'source2' from module 'pkg'; the module executes module level statement and it might call sys.exit().
```

うまくいくソースと上記エラーが出るソースの違いを確認しているのですが、
どうも以下の差異が影響しているように思われます。

ソースはテストソースとフォルダを分ける目的で
pkgフォルダの配下に置いています。
この配下のソース間でimportする際には、
```
from pkg import source2
from pkg import source3
```
のようにしてインポートしていますが、インポートする側はエラーになり、インポートされるだけのソースはエラーになっていないようです。
インポートの仕方が悪いのか、インポート時に走行している処理が他にまだあるのかもしれません。

念のため確認したいのですが、import時に処理が走らないようにする必要がある、というのは
`a = func()`
のようなものはfuncの中で処理が走るためダメで
`a = 0`
のようなものはグローバル変数定義でOKという認識でよいでしょうか。

[hayataka2049]

ちょっと細かい動作については未確認です。あしからず。

ところでWARNING「警告」なのでエラーではないのですが、結果のファイルは生成されていないのですか？

[palayo]

ありがとうございます。細かい点はこちらで実際にやってみるので大丈夫です。
警告なのですが、警告が出ているソースの結果ファイルは生成されていませんでした。
その後、以下のようなpkg配下のモジュールをインポートする行をすべてコメントアウトしたところ、
ちゃんとhtml出力できることを確認できました。
from pkg import source2

しかし、html出力のたびにloggerやimportのコメントアウトをするのも負担が大きいです。
良い方法があるとよいのですが、そもそも自分の使い方がおかしいのかもしれません。
フォルダ構成やimport方法、loggerの初期化の記載場所など、
何か修正すべき点がありましたら、ご指摘いただけると助かります。