Python的獅身人面像：從超

Question

編輯「繼承」方法的文檔： 截至目前（獅身人面像1.4.9）似乎有沒有辦法告訴獅身人面像做什麼我想（見GitHub上issue）。 Brecht Machiels的accepted answer以另一種方式解決了這個問題，直到有一天斯芬克斯能夠做到這一點。

描述： 我想用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)) 

運行獅身人面像，apidoc（sphinx-apidoc -o apidoc project -f）生成以下文件：

• 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在隨後make html默認index.rst產生兩個類和它們的方法一個基本的HTML文檔。不幸的是，Derived.give的文檔字符串爲空。

問： 有沒有辦法告訴獅身人面像在this描述，張貼每個單獨的方法拿父母的方法的文檔沒有裝飾的魔力？

Answer 1

您可以通過爲抽象基類使用元類來自動管理docstrings。以下是這種元類的一個非常基本的實現。它需要擴展以正確處理多個基類和角落案例。

# -*- 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()時工作。