Sphinx不读取我的函数docString?

2024-06-26 00:12:07 发布

您现在位置:Python中文网/ 问答频道 /正文

我试图auto docstring我的项目中的每个模块都有函数,但是sphinx-apidoc不读取我的函数和文档字符串

我的项目结构是这样的

mktpip
├── docs
│   ├── Makefile
│   ├── build
│   ├── make.bat
│   └── source
│       ├── _static
│       │   └── logo.jpg
│       ├── _templates
│       ├── conf.py
│       ├── index.rst
│       └── reference
│           ├── me.rst
│           └── modules.rst
├── mktpip
│   ├── __init__.py
│   ├── __init__.pyc
│   └── me
|.      |- my_module.py
│       └── __init__.py
├── run.py
├── setup.cfg
└── setup.py

我试图从中自动记录文档的源代码是mktpip/me/my_module.py,它有这样一个简单的函数

def my_module(a,b):
    """Calculate two number
    
    Args:
        a (int): operand 1
        b (int): operand 2
    
    Returns:
        int: sum of a + b
    """
    return a+b

要自动docstring,我执行了以下步骤:

(venv) ➜  mktpip copy git:(dev) ✗ sphinx-apidoc -f -o docs/source/reference mktpip/me
Creating file docs/source/reference/me.rst.
Creating file docs/source/reference/modules.rst.

然后,我从*.rst文件生成HTML

(venv) ➜  docs git:(dev) ✗ make clean && make html
Removing everything under 'build'...
Running Sphinx v1.8.5
making output directory...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 31 source files that are out of date
updating environment: 31 added, 0 changed, 0 removed
/Users/narun/Documents/mktpip/venv/lib/python2.7/site-packages/sphinx/util/nodes.py:94: FutureWarning:                                                                                                                                        
   The iterable returned by Node.traverse()
   will become an iterator instead of a list in Docutils > 0.16.
  for classifier in reversed(node.parent.traverse(nodes.classifier)):

然后,我打开一个index.html文件,发现它没有读取模块me的函数

(venv) ➜  docs git:(dev) ✗ open build/html/index.html

这是输出的结果:

enter image description here

没有my函数my_module()及其docString

conf.py内,我添加了

docs_dir = os.path.dirname(os.path.dirname(__file__))
sys.path.insert(0, docs_dir)

除上述内容外,这里还有me.rst

me package
==========

Submodules
----------

me.my\_module module
--------------------

.. automodule:: mktpip.me.my_module
    :members:
    :undoc-members:
    :show-inheritance:


Module contents
---------------

.. automodule:: mktpip.me
    :members:
    :undoc-members:
    :show-inheritance:

这出了什么问题?请帮助我,谢谢


Tags: of函数pydocssourcevenvmyhtml