Edit: 截至目前(Sphinx 1.4.9),似乎没有办法告诉狮身杆位做我想做的事(请参阅Github上的issue)。 Brecht Machiels的申请答案以另一种方式解决了该问题,直到狮身人面像有一天能够做到这一点。
描述:
我正在尝试使用sphinx-apidoc记录一个Python项目。狮身人面像的配置几乎默认,我只是包括'sphinx.ext.autodoc'
。它一般起作用,但是派生的类并未像我期望的那样继承其超类的方法文档。
示例:
考虑一个非常简约的Python包装,称为project
。除了一个空__init__.py
base.py
它仅由一个文件组成(
# -*- coding: utf-8 -*
import abc
class Superclass(object):
"""The one to rule them all"""
@abc.abstractmethod
def give(self, ring):
"""Give out a ring"""
pass
class Derived(Superclass):
"""Somebody has to do the work"""
def give(self, ring):
print("I pass the ring {} to you".format(ring))
,请参见下文)
sphinx-apidoc -o apidoc project -f
运行sphinx-apidoc(
apidoc/modules.rst
)生成以下文件:
project
=======
.. toctree::
:maxdepth: 4
project
apidoc/project.rst
project package
===============
Submodules
----------
project.base module
-------------------
.. automodule:: project.base
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: project
:members:
:undoc-members:
:show-inheritance:
apidoc/modules.rst
index.rst
在默认情况下,然后为两个类及其方法生成基本的HTML文档。不幸的是,
make html
的docstring是空的。
问题:是否有一种方法告诉狮身人面像在没有装饰器魔术的情况下使用父母的方法文档,如
您可以通过为抽象基类采用元素来自动管理DOCSTRINGS。以下是这种元素的非常基本的实现。它需要扩展以正确处理多个基类和角案例。
Derived.give
this这是一个更好的解决方案,而不是让Sphinx做到这一点,因为在派生类中呼叫# -*- coding: utf-8 -*
import abc
class SuperclassMeta(type):
def __new__(mcls, classname, bases, cls_dict):
cls = super().__new__(mcls, classname, bases, cls_dict)
for name, member in cls_dict.items():
if not getattr(member, '__doc__'):
member.__doc__ = getattr(bases[-1], name).__doc__
return cls
class Superclass(object, metaclass=SuperclassMeta):
"""The one to rule them all"""
@abc.abstractmethod
def give(self, ring):
"""Give out a ring"""
pass
class Derived(Superclass):
"""Somebody has to do the work"""
def give(self, ring):
print("I pass the ring {} to you".format(ring))
时,这也将起作用。
help()
和
autodoc_inherit_docstrings