我正在尝试学习如何使用sphinx生成文档。我有一个数据包它的名字测试，它有一个名为test_module的模块。 sphinx-quickstart脚本运行良好。它会创建所有相关文件和目录。
但我无法通过生成的html文件看到该类及其方法。我只能在module_index中看到test_module。
index.rst：
.. test documentation master file, created by
sphinx-quickstart on Tue Apr 19 13:51:42 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to test's documentation!
================================
Contents:
.. toctree::
:maxdepth: 4
.. automodule:: test
:members:
:show-inheritance:
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
test_module.py
""This module illustrates how to write your docstring in OpenAlea
and other projects related to OpenAlea."""
class MainClass1(object):
"""This class docstring shows how to use sphinx and rst syntax
The first line is brief explanation, which may be completed with
a longer one. For instance to discuss about its methods. The only
method here is :func:`function1`'s. The main idea is to document
the class and methods's arguments with
- **parameters**, **types**, **return** and **return types**::
:param arg1: description
:param arg2: description
:type arg1: type description
:type arg1: type description
:return: return description
:rtype: the return type description
- and to provide sections such as **Example** using the double commas syntax::
:Example:
followed by a blank line !
which appears as follow:
:Example:
followed by a blank line
- Finally special sections such as **See Also**, **Warnings**, **Notes**
use the sphinx syntax (*paragraph directives*)::
.. seealso:: blabla
.. warnings also:: blabla
.. note:: blabla
.. todo:: blabla
.. note::
There are many other Info fields but they may be redundant:
* param, parameter, arg, argument, key, keyword: Description of a
parameter.
* type: Type of a parameter.
* raises, raise, except, exception: That (and when) a specific
exception is raised.
* var, ivar, cvar: Description of a variable.
* returns, return: Description of the return value.
* rtype: Return type.
.. note::
There are many other directives such as versionadded, versionchanged,
rubric, centered, ... See the sphinx documentation for more details.
Here below is the results of the :func:`function1` docstring.
"""
def function1(self, arg1, arg2, arg3):
"""returns (arg1 / arg2) + arg3
This is a longer explanation, which may include math with latex syntax
:math:`\\alpha`.
Then, you need to provide optional subsection in this order (just to be
consistent and have a uniform documentation. Nothing prevent you to
switch the order):
- parameters using ``:param <name>: <description>``
- type of the parameters ``:type <name>: <description>``
- returns using ``:returns: <description>``
- examples (doctest)
- seealso using ``.. seealso:: text``
- notes using ``.. note:: text``
- warning using ``.. warning:: text``
- todo ``.. todo:: text``
**Advantages**:
- Uses sphinx markups, which will certainly be improved in future
version
- Nice HTML output with the See Also, Note, Warnings directives
**Drawbacks**:
- Just looking at the docstring, the parameter, type and return
sections do not appear nicely
:param arg1: the first value
:param arg2: the first value
:param arg3: the first value
:type arg1: int, float,...
:type arg2: int, float,...
:type arg3: int, float,...
:returns: arg1/arg2 +arg3
:rtype: int, float
:Example:
>>> import template
>>> a = template.MainClass1()
>>> a.function1(1,1,1)
2
.. note:: can be useful to emphasize
important feature
.. seealso:: :class:`MainClass2`
.. warning:: arg2 must be non-zero.
.. todo:: check that arg2 is non zero.
"""
return arg1/arg2 + arg3
if __name__ == "__main__":
import doctest
doctest.testmod()