Question

使用Sphinx autodoc构建文档时遇到问题。我的项目由包含类的不同模块组成。正确生成这些模块的文档。

但是有一个模块（在我的例子中称为 controller.py ）包含用于初始化其他模块中的对象以及启动线程等的代码。

由于Sphinx在构建文档时执行了模块代码，因此我添加到我的controller.py中以防止代码运行：

if __name__ == '__main__':
    main()

此外，所有执行的代码都包含在主函数中：

''' A. general description of controller.py module '''
import mymod1, mymod2, mymod3

    def main():
       ''' B. initializing obj1 '''
       obj1 = mymod1.class1()
       obj2 = mymod2.class2()
       ''' C. doing something '''
       obj2.run()

if __name__ == '__main__':
    main()

问题是Sphinx对于controller.py的输出，其中仅包含外部主函数：

A. general description of controller.py module

controller.main()

我想要实现的是，也可以看到注释B.和C.这在其他模块中没有问题，因为内部代码包含在类中。但是这里忽略了函数中包含的代码。

有没有办法在不改变Python代码的情况下获得结果？我想保持代码和文档之间的依赖关系低。

任何提示都表示赞赏。感谢。

编辑：我切换到apidoc，但问题是类似的。我可以看到我在main（）中的注释，但是没有注释main中的函数定义。例如：

def main():
   ''' This comment is visible '''
   def smallfunction():
      ''' This comment is NOT visible '''

此外，如果有可能包含源代码而不仅仅是API，那将会很棒。＆lt; - 编辑：此部分现已解决。在docs / source / config.py中必须将条目'sphinx.ext.viewcode'添加到扩展以包含指向源代码的链接

如何使用Sphinx autodoc记录我的主要功能？

0 个答案: