让Sphinx识别导入的类和函数，而不是模块 [英] Have Sphinx recognize imported classes and functions instead of modules

问题描述

假设我有一个项目，结构如下：

mypackage
├── mypackage
│   ├── __init__.py
│   ├── someclass.py
│   └── somefunction.py
└── setup.py

然后我有__init__.pyAs：

from mypackage.someclass import someclass
from mypackage.somefunction import somefunction

和someclass.pyAS：

class Someclass:
...

和somefunction.pyAS：

def somefunction:
...

无法向用户"隐藏"mypackage.someclass.Someclass和mypackage.somefunction.somefunction，因此只有mypackage.Someclass和mypackage.somefunction可用，对吗？

但问题是，Sphinx实际上记录的是mypackage.someclass.Someclass和mypackage.somefunction.somefunction，而不是mypackage.Someclass和mypackage.somefunction。

对于mypackage.somefunction.somefunction，如果我导入mypackage，它甚至无法访问，这是非常糟糕的。

那么，是否可以拥有Sphinx文档mypackage.Someclass和mypackage.somefunction？根据我在其他答案上看到的，这可以通过编辑__module__或使用autoclass来完成，但我现在无法确定

推荐答案

按照Sphinx文档sphinx.ext.autodoc – Include documentation from docstrings中的说明使用AutoClass。

为了使AutoClass(和任何其他AutoDoc功能)正常工作，该模块必须是可导入的。

AutoDoc将记录您的模块的API，您可以将文档字符串作为叙述性文档添加为reStrufredText格式，以解释用法。

最好将docs目录放在您的程序包目录旁边。

mypackage
├── docs
│   ├── conf.py
│   ├── other sphinx stuff
│   └── index.rst
├── mypackage
│   ├── __init__.py
│   ├── someclass.py
│   └── somefunction.py
└── setup.py

在docs内组织.rst文件。您的模块是一个API，所以您可以像这样组织.rst文件：

mypackage
├── docs
    └── api
        ├── someclass.rst
        └── somefunction.rst

在api目录中的每个文件中，使用适当的语法。

.. autoclass:: someclass
.. autofunction:: somefunction

前面提到的Sphinx文档中还包括几个选项。

这篇关于让Sphinx识别导入的类和函数，而不是模块的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！