使用Sphinx自动记录python类，模块 [英] Using sphinx to auto-document a python class, module

问题描述

我已经安装了 Sphinx ，以便记录一些我正在使用的Python模块和类。虽然标记语言看起来非常不错，但我还没有设法自动记录Python代码。

I have installed Sphinx in order to document some Python modules and class I'm working on. While the markup language looks very nice, I haven't managed to auto-document a Python code.

基本上，我有以下Python模块：

Basically, I have the following Python module:

SegLib.py

其中有一个名为 Seg 的类。我想在生成的Sphinx文档中显示类和模块的文档字符串，并向其中添加更多格式化的文本。

And A class called Seg in it. I would like to display the docstrings of the class and module within the generated Sphinx document, and add further formatted text to it.

我的索引。 rst 看起来像这样：

Contents:

.. toctree::
:maxdepth: 2

chapter1.rst

chapter1.rst ：

This is a header
================
Some text, *italic text*, **bold text**

* bulleted list.  There needs to be a space right after the "*"
* item 2

.. note::
   This is a note.

See :class:`Seg`

但是 Seg 仅以粗体显示，而不链接到该类的自动生成的文档。

But Seg is just printed in bold, and not linked to an auto-generated documentation of the class.

尝试：
请参见：class： Seg
Module：mod：'SegLib'
Module：mod：'SegLib.py'

Trying: See :class:Seg Module :mod:'SegLib' Module :mod:'SegLib.py'

也没有帮助。
有任何想法或好的教程链接吗？

Didn't help, too. Any ideas or good tutorial links?

编辑：将SegLib更改为段（谢谢，iElectric！），并将Chapter1.rst更改为：
：mod：段模块
-------------------- ------

changed SegLib to segments (thanks, iElectric!), and changed chapter1.rst to: The :mod:segments Module --------------------------

.. automodule:: segments.segments

.. autoclass:: segments.segments.Seg

仍然，Sphinx无法直接在类中记录函数，或更好-将类中的所有功能自动添加到文档中。尝试过：

Still, can't get Sphinx to directly document functions within a class, or better - to automatically add all the functions within a class to the document. Tried:

.. autofunction:: segments.segments.Seg.sid

并得到：

autodoc can't import/find function 'segments.segments.Seg.sid', it reported error: "No module named Seg"

有什么想法可以使用短命令自动记录功能和类吗？

Any ideas how to auto-document the functions and classes with a short command?

Udi

推荐答案

添加到文件的开头：

.. module:: SegLib

尝试使用：autoclass：

Try using :autoclass: directive for class doc.

BTW：模块名称应为小写。

BTW: module names should be lower_case.

编辑： 我从阅读其他源文件中学到了很多东西。

这篇关于使用Sphinx自动记录python类，模块的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！