問題有沒有一種方法可以生成子類的 sphinx 文檔，而無需在 GitLab CI（或任何類似的 CI 工具）上安裝包含其父類的庫？編輯：我有 7 個(gè)這樣的課程，大約有 7 個(gè)。平均每個(gè)類有 10 個(gè)成員函數(shù)需要記錄。因此，強(qiáng)烈推薦自動(dòng)化解決方案，因?yàn)閷⑽臋n字符串硬編碼到文件中會(huì)花費(fèi)太多時(shí)間.rst。如果僅通過更改 Sphinx 設(shè)置無法解決問題，那么我只會(huì)接受提供明確說明以生成和發(fā)布所需文檔的答案。語境具體來說，我創(chuàng)建了一個(gè)子類tensorflow.keras.callbacks.Callback?，并希望在文檔頁面上顯示其文檔字符串。默認(rèn)情況下，Sphinx 必須導(dǎo)入生成文檔的所有內(nèi)容。tensorflow但僅僅為此在 CI 映像上安裝（以及數(shù)十個(gè)其他庫，總計(jì)達(dá)數(shù) GB）似乎并不正確。我只想顯示我的文檔字符串，我不關(guān)心他們的父類。autodoc_mock_imports這就是我在conf.py（Sphinx配置文件）中開啟的原因。文檔的構(gòu)建沒有錯(cuò)誤，但缺少該子類的文檔。在下面的MWE中，定制的類是keras_callback.py.?sphinx 指令包含keras_callback.rst如下。..?automodule::?keras_callback
????:members:
????????:inherited-members:最小工作示例我的 GitLab 存儲(chǔ)庫上有MWE?和Sphinx 生成的文檔來重現(xiàn)該問題。子類所需的文檔如下所示。至少，應(yīng)該顯示我的自定義函數(shù)的文檔。可以關(guān)閉父類的成員函數(shù)。
2 回答
波斯汪
TA貢獻(xiàn)1811條經(jīng)驗(yàn) 獲得超4個(gè)贊
除了從 Python 代碼中提取文檔的“自動(dòng)”指令（例如automodule和autoclass）之外，Sphinx 還提供“非自動(dòng)”指令（module等class），其中所有文檔都放入 .rst 文件中。
我的建議是替換.. automodule:: keras_callback為以下內(nèi)容：
..?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貢獻(xiàn)2012條經(jīng)驗(yàn) 獲得超12個(gè)贊
我終于找到了一個(gè)簡(jiǎn)單的解決方法：本地構(gòu)建，然后使用本地構(gòu)建的頁面覆蓋 CI 構(gòu)建的頁面。如果所需的頁面不需要頻繁重建，那么此解決方案可以節(jié)省大量對(duì)成員進(jìn)行硬編碼的時(shí)間。
腳步
本地構(gòu)建，無需
autodoc_mock_importsinconf.py.將正確的網(wǎng)頁 (
keras_callback.html) 復(fù)制到_static文件夾。重新啟用
autodoc_mock_imports.添加一個(gè)
cp命令來覆蓋 CI 構(gòu)建的頁面.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
提交、推送并檢查網(wǎng)頁。為這個(gè)特定的 MWE 工作（未在存儲(chǔ)庫中顯示）。
當(dāng)然，缺點(diǎn)是維護(hù)者必須在更新頁面時(shí)手動(dòng)重建該頁面。但這對(duì)于許多小型獨(dú)立項(xiàng)目來說應(yīng)該足夠了，因?yàn)槲臋n發(fā)布通常只發(fā)生在開發(fā)的最后階段。
添加回答
舉報(bào)
0/150
提交
取消