問題有沒有一種方法可以生成子類的 sphinx 文檔，而無需在 GitLab CI（或任何類似的 CI 工具）上安裝包含其父類的庫？編輯：我有 7 個這樣的課程，大約有 7 個。平均每個類有 10 個成員函數需要記錄。因此，強烈推薦自動化解決方案，因為將文檔字符串硬編碼到文件中會花費太多時間.rst。如果僅通過更改 Sphinx 設置無法解決問題，那么我只會接受提供明確說明以生成和發布所需文檔的答案。語境具體來說，我創建了一個子類tensorflow.keras.callbacks.Callback?，并希望在文檔頁面上顯示其文檔字符串。默認情況下，Sphinx 必須導入生成文檔的所有內容。tensorflow但僅僅為此在 CI 映像上安裝（以及數十個其他庫，總計達數 GB）似乎并不正確。我只想顯示我的文檔字符串，我不關心他們的父類。autodoc_mock_imports這就是我在conf.py（Sphinx配置文件）中開啟的原因。文檔的構建沒有錯誤，但缺少該子類的文檔。在下面的MWE中，定制的類是keras_callback.py.?sphinx 指令包含keras_callback.rst如下。..?automodule::?keras_callback
????:members:
????????:inherited-members:最小工作示例我的 GitLab 存儲庫上有MWE?和Sphinx 生成的文檔來重現該問題。子類所需的文檔如下所示。至少，應該顯示我的自定義函數的文檔?？梢躁P閉父類的成員函數。
2 回答
波斯汪
TA貢獻1811條經驗 獲得超4個贊
除了從 Python 代碼中提取文檔的“自動”指令（例如automodule和autoclass）之外，Sphinx 還提供“非自動”指令（module等class），其中所有文檔都放入 .rst 文件中。
我的建議是替換.. automodule:: keras_callback為以下內容：
..?class::?keras_callback.MyKerasCallback ? ???An?inherited?Keras?``Callback``?class. ? ???..?method::?__init__(dic=None)? ??????Constructor ? ???..?method::?on_epoch_begin(epoch,?logs=None)??????????? ??????Inherited?method ? ???..?method::?custom_method ? ??????Custom?method ..?autofunction::?keras_callback.util_func
繁花如伊
TA貢獻2012條經驗 獲得超12個贊
我終于找到了一個簡單的解決方法：本地構建，然后使用本地構建的頁面覆蓋 CI 構建的頁面。如果所需的頁面不需要頻繁重建，那么此解決方案可以節省大量對成員進行硬編碼的時間。
腳步
本地構建，無需
autodoc_mock_importsinconf.py.將正確的網頁 (
keras_callback.html) 復制到_static文件夾。重新啟用
autodoc_mock_imports.添加一個
cp命令來覆蓋 CI 構建的頁面.gitlab-ci.yml
image: python:3.7-alpine pages: script: - pip install sphinx sphinx-rtd-theme recommonmark - sphinx-build -d _build/doctrees . _build/html - mv _build/html public - cp _static/keras_callback.html public artifacts: paths: - public only: - master
提交、推送并檢查網頁。為這個特定的 MWE 工作（未在存儲庫中顯示）。
當然，缺點是維護者必須在更新頁面時手動重建該頁面。但這對于許多小型獨立項目來說應該足夠了，因為文檔發布通常只發生在開發的最后階段。
添加回答
舉報
0/150
提交
取消