是否有可能將Sphinx automodule擴展到Python以外的域？

我正在尋找使用Sphinx來記錄VHDL源代碼。理想情況下，我想能夠採取一個VHDL類型是這樣的：是否有可能將Sphinx automodule擴展到Python以外的域？

type T_SDRAM_REQ is record 
    req  : STD_LOGIC; 
    wr  : STD_LOGIC; 
    address : STD_LOGIC_VECTOR; 
    wr_data : STD_LOGIC_VECTOR; 
    wr_ben : STD_LOGIC_VECTOR; 
end record T_SDRAM_REQ;

，並使用RST指令是這樣的：

.. vhdl:type:: sdram_pack.T_SDRAM_REQ is record 
    :members:

提取所有字段從源代碼和RST - 如果是我的話。

我已經創建了一個獅身人面像域，但它對我來說只有這一點還不夠 - 這真的只是一堆自定義指令。我真正想要的東西類似於autoclass或automodule，它掃描Python源文件以生成指令。

但是據我所知，Sphinx automodule的功能只適用於Python。是否可以擴展Sphinx以包含其他語言的類似功能？在VHDL中，可能會被稱爲autopackage或autoentity，在C++中，我猜autonamespace或不同的autoclass？我可以以某種方式將vhdl:autopackage::指令添加到我的域中嗎？從Sphinx源代碼中我可以看出，我不認爲automodule指令是Python域的一部分。

來源

2016-08-18 Andy Royal

是的，內置的autodoc擴展僅適用於Python。但你所要求的應該是可能的。例如，對於Java，有一個名爲javasphinx的擴展（https://github.com/bronto/javasphinx）。我不明白爲什麼類似的東西不能用於VHDL。 – mzjn

@mzjn感謝您指點我，但是當它添加Java域和apidoc功能時，據我所知它不會添加autodoc，這就是我所追求的。不能誠實地說我有Java設置來測試它。 –

相關：http://stackoverflow.com/q/37420560/407651 – mzjn

我自己的問題的答案是：是的。我設法做到了，但這並不容易，結果也遠非完美。

雖然Sphinx Domain API已經設置了一些通用的基類和特定於Python的子類，但autodoc並不能這樣說。一些Python autodoc類可以用作基類，但需要大量的替代。

我的車博士系統的組成部分是：

新的指令VHDLAutoDirective的AutoDirective一個子類，它保持了資料員和特殊attrgetters和裝飾單獨登記「VHDL：汽車」從的開始指令名稱而不只是「自動」。與原文一樣，這會調用特定於對象的記錄器。
新的記錄。一個通用的VHDL記錄器基類VHDLDocumenter，然後是每個VHDL對象的子類。這些文檔編寫者完成所有繁重的工作，從指令中獲取選項和內容，並解析VHDL以生成內容。這裏的關鍵問題是Python autodoc依賴於正在記錄安裝的模塊。由於Sphinx是用Python編寫的，所以很容易import那些已安裝的模塊並以這種方式提取所有必需的信息，例如__doc__可用於提取文檔。對於任何其他語言，您將必須首先找到包含您想要記錄的對象的文件，然後對其進行解析。爲了解決第一個問題，我添加了一個current-file指令，爲所有後續自動指令指定一個文件，併爲我的記錄器基類指定一個file選項，以允許指定每個指令的文件。這有點笨拙，因爲文件的路徑與我的版本庫相關，並且假設Sphinx在那裏運行 - 如果Sphinx運行在子目錄中，它將不起作用。對於第二個我寫了一個基本的記號器和解析器，然後才認爲將原始源代碼複製到code-block指令中可能會更好 - 現在我可以選擇執行任一操作。
add_autodocumenteradd_autodocumenter函數在我的域中，它在域中註冊一個指令，然後導入我的autodoc模塊並調用add_documenter函數來註冊文檔。 autodoc模塊的設置功能然後在auto指令的每個對象記錄器上調用add_autodocumenter。這與Python autodoc所做的相似，但是Python版本會將其指令註冊到應用程序而不是域。

還有很大的改進空間，但至少它可以作爲一個概念驗證，可以做到這一點。

來源

2016-09-13 11:34:21

是否有可能將Sphinx automodule擴展到Python以外的域？

回答

相關問題