如何在sphinx autodoc中專門記錄文檔

我正在用Sphinx記錄項目我想創建autoclass::指令的專用版本，該指令允許我修改某些類的文檔字符串。如何在sphinx autodoc中專門記錄文檔

以下是我嘗試過的一件事：搜索獅身人面像源，我發現autoclass指令是通過ClassDocumenter object創建的。在此之後，我的想法是爲感興趣的類註冊一個ClassDocumenter的子類，然後覆蓋get_doc來修改文檔字符串。

這是我在這樣的擴展嘗試：

from six import class_types 
from sphinx.ext.autodoc import ClassDocumenter 
from testmodule import Foo # the class that needs modified documentation 


class MyClassDocumenter(ClassDocumenter): 
    objtype = 'myclass' 
    priority = 20 # higher priority than ClassDocumenter 

    @classmethod 
    def can_document_member(cls, member, membername, isattr, parent): 
     return isinstance(member, class_types) and issubclass(member, Foo) 

    def get_doc(self, encoding=None, ignore=1): 
     doc = super(MyClassDocumenter, self).get_doc(encoding, ignore) 
     # do something to modify the output documentation 
     doc[0].insert(0, "ADD SOMETHING TO THE DOC") 
     return doc 

def setup(app): 
    app.add_autodocumenter(MyClassDocumenter)

的問題是，當我運行此我得到一個錯誤：ERROR: Unknown directive type "py:myclass".看來登記記錄器是不夠的，註冊的相關指示，但我在獅身人面像源中找不到任何線索來告訴我這樣的註冊是如何發生的。這不像使用標準add_directive()方法那麼簡單，因爲我沒有明確的註冊指令。

我該如何正確完成獅身人面像中的自動文檔記錄的這種專業化？

（注：全套文件重現錯誤，請in this gist）

來源

2016-09-19 jakevdp

要修改文檔字符串，可能更容易使用'autodoc-process-docstring'事件。請參閱http://www.sphinx-doc.org/en/stable/ext/autodoc.html#event-autodoc-process-docstring。 – mzjn

謝謝@mzjn，看起來很有希望！我會試試這個方法。 – jakevdp

我發現在Docutils markup API

Directives are handled by classes derived from docutils.parsers.rst.Directive. They have to be registered by an extension using Sphinx.add_directive() or Sphinx.add_directive_to_domain().

東西是不是你在找什麼？

來源

2016-09-19 04:24:19

感謝您的評論。這並沒有什麼幫助 - 我知道如何註冊新的指令。我不清楚的是，sphinx autodoc如何在Documenter子類創建的各種指令內部執行此操作。 – jakevdp

Documenter類在適當時需要現有的指令來應用。這可以是「內置」指令，也可以是您創建並註冊的自定義指令。無論哪種方式，要使用的指令都由directivetype類屬性指定。您可以顯式指定該值：

class MyClassDocumenter(ClassDocumenter): 
    directivetype = 'foo' # corresponds to :foo: in the doc source 
    objtype = 'bar' 
    priority = 20

或者說，它看起來像你可以省略directivetype，它會默認使用相同的值objtype。（這是一個有教養的猜測）

那麼問題是：你有沒有註冊一個新的指令:myclass:？如果不是，我認爲這是問題。或者，如果您想要使用其他指令（無論是內置的還是自定義的），則答案可能是通過在您的Documenter類定義中包含directivetype的值來明確指定。

來源

2016-09-19 13:14:21 bigreddot

感謝您的迴應 - 這是有道理的，但我真正想要的是繼承和修改在''autoclass''中發生的事情。除非我弄錯了，否則這個直接的定義不是在任何地方明確定義的，而是通過''ClassDocumenter''隱式創建的。我錯了嗎？如果是這樣，autoclass'指令的定義在哪裏，以便我可以繼承它並擴展它來定義''myclass''指令？ – jakevdp

好的，但是你想通過使用現有的'：class：'指令來修改它，但讓文檔員在「更高級別」上做了不同的事情嗎？或者你想自定義'：class：'指令嗎？如果前者，我認爲你只需要'directivetype ='class''。如果是後者，python域'：class：'指令在這裏定義：https：//github.com/sphinx-doc/sphinx/blob/master/sphinx/domains/python.py#L317-L339 – bigreddot

我是不完全確定如何回答。也許我應該改述一下：我想要的只是捕獲''：autoclass：''中發生的任何事情的輸出，爲特定對象修改它並將其傳遞迴autodoc進程。從上面的@ mzjn的評論看來，看起來事件掛鉤可能比沿着這個Documenter/Directive專業化的兔子洞更好。 – jakevdp

如何在sphinx autodoc中專門記錄文檔

回答

相關問題