Sphinx 无法导入某些模块

如何解决Sphinx 无法导入某些模块

我正在为代码库生成文档。在构建文档时，我可以看到它们仅针对某些模块构建，并且许多模块没有记录在控制台中并带有警告 - Failed to import <module-name>。即使在阅读官方文档和 stackoverflow 上的多个答案后，我也无法理解为什么它不起作用。

以下是代码库的结构：-

docs
├── Makefile
├── make.bat
├── source
│   ├── _templates
│   │   ├── custom-class-template.rst
│   │   └── custom-module-template.rst
│   ├── conf.py
│   └── index.rst
extract
│   ├── __init__.py
│   ├── avro_converter
│   │   ├── JSON_converter.py
│   │   ├── __init__.py
│   ├── helpers
│   │   ├── __init__.py
│   │   └── helpers.py

在 index.rst 文件中，我尝试为 extract 模块导入文档，如下所示 [ref]:-

Welcome to documentation!
======================================

Modules
======================================

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

   extract

使用以下模板呈现文档：-

custom-module-template.rst

{{ fullname | escape | underline}}

.. automodule:: {{ fullname }}

   {% block attributes %}
   {% if attributes %}
   .. rubric:: Module attributes

   .. autosummary::
      :toctree:
      :nosignatures:
   {% for item in attributes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

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

   .. autosummary::
      :toctree:
      :nosignatures:
   {% for item in functions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

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

   .. autosummary::
      :toctree:
      :template: custom-class-template.rst
      :nosignatures:
   {% for item in classes %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

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

   .. autosummary::
      :toctree:
      :nosignatures:
   {% for item in exceptions %}
      {{ item }}
   {%- endfor %}
   {% endif %}
   {% endblock %}

{% block modules %}
{% if modules %}
.. autosummary::
   :toctree:
   :template: custom-module-template.rst
   :nosignatures:
   :recursive:
{% for item in modules %}
   {{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

对于构建文档，以下是 config.py 中的配置：-

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

project = 'sample'
copyright = '2021,Vineet Sharma'
author = 'Vineet Sharma'

extensions = [
    'sphinx.ext.autodoc','sphinx.ext.autosummary','sphinx.ext.coverage','sphinx.ext.napoleon','sphinx.ext.viewcode'
]

templates_path = ['_templates']
exclude_patterns = ['_build','_templates']
html_theme = 'sphinx_rtd_theme'

html_static_path = []
autosummary_generate = True

对于文件JSON_converter，里面的函数使用的依赖项很少，如下：-

JSON_converter.py

import json
import multiprocessing
import os
import random
import string
import sys
import traceback
from configparser import ConfigParser
from datetime import datetime
from imp import reload

import boto3
import fastavro
import pandas as pd

# get current directory
current_dir = os.getcwd()
sys.path.append(os.path.join(os.path.dirname(current_dir)))
reload(sys)

# helpers in another folder inside extract which contains a file named helpers.py; this file gets documented without any error
from helpers.helpers import enqueue,make_local_dir,remove_dir,read_csv

# parent directory
config_path = os.path.join(os.path.dirname(current_dir),"config.ini")
CONfig = ConfigParser()
CONfig.read(config_path)

....
....

在运行 make html 命令时出现以下错误：-

WARNING: [autosummary] Failed to import 'extract.avro_converter.JSON_converter': no module named extract.avro_converter.JSON_converter

/Users/espm2381/epi/titan/docs/source/_autosummary/extract.avro_converter.rst.rst:24: WARNING: autosummary: Failed to import extract.avro_converter.JSON_converter

出现此类错误的原因之一是您的环境中没有安装模块。但是，我在我的环境中安装了所有依赖项，如下所示：-

alabaster==0.7.12
awscli==1.19.16
Babel==2.9.1
beautifulsoup4==4.9.3
boto3==1.17.16
botocore==1.20.16
certifi==2021.5.30
charset-normalizer==2.0.3
click==8.0.1
colorama==0.4.3
docutils==0.15.2
et-xmlfile==1.0.1
fastavro==1.3.4
furo==2021.7.5b38
idna==3.2
imagesize==1.2.0
jdcal==1.4.1
Jinja2==2.11.3
jmespath==0.10.0
joblib==1.0.1
MarkupSafe==1.1.1
numpy==1.20.1
openpyxl==3.0.6
packaging==21.0
pandas==1.2.2
pyarrow==3.0.0
pyasn1==0.4.8
pydata-sphinx-theme==0.6.3
Pygments==2.9.0
pyparsing==2.4.7
python-dateutil==2.8.1
python-snappy==0.6.0
pytz==2021.1
PyYAML==5.4.1
requests==2.26.0
rsa==4.7.2
s3transfer==0.3.4
scikit-learn==0.24.1
scipy==1.7.0
sentry-sdk==1.1.0
six==1.15.0
snowballstemmer==2.1.0
soupsieve==2.2.1
Sphinx==4.1.2
sphinx-book-theme==0.1.1
sphinx-rtd-theme==0.5.2
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5
threadpoolctl==2.2.0
urllib3==1.26.3

一周前我一直试图找出这个问题，但都是徒劳的。希望就该问题提供建议或提示。