使用Sphinx進行Python項目文檔的正確工作流程是什麼？

Question

我想使用Sphinx來記錄目前沒有很好記錄的大型項目。特別是我想用sphinx-apidoc來生成代碼中的文檔。

但是我也想要一些關於如何使用這個項目的教程的頁面，但是當我打電話給sphinx-apidoc時，它似乎一次生成了整個文檔。

所以我的問題是：這裏的正確工作流程是什麼，所以我可以編寫手動編寫的教程頁面，同時更新代碼中的文檔？請注意，如果我更新手動編寫的教程頁面（例如包含在index.txt中）並運行sphinx-apidoc，那麼隨着整個文檔一次生成，我將丟失它們。

一般來說，有沒有任何指導方針如何進行建設文件？

注意：不方便之處在於基本過程假定您已經擁有所有代碼文檔，並且在生成文檔時不會進行任何更新。至少這是我需要解決的。

Answer 1

首先運行sphinx-quickstart並接受默認設置您的基本結構這僅僅是做一次和編輯的內容index.rst節的表指向您的教程，先介紹一下，等等 - 的你至少在單獨的.rst文件中概述你的教程。您還可以編輯config.py添加車博士 - 從網站：

當記錄Python代碼，通常把很多 文檔的源文件，在文件的字符串。 Sphinx 支持從模塊中加入 擴展名（擴展名爲Python模塊，爲Sphinx項目提供其他 功能），稱爲「autodoc」。

爲了使用autodoc，您需要在conf.py中激活它，方法是將 字符串'sphinx.ext.autodoc'放入分配給 擴展配置值的列表中。然後，您可以在 處理一些其他指令。

例如，文件）io.open功能（，讀其簽名 和源文件文檔字符串，你會這樣寫：

..自動功能:: io.open您還可以記錄整個班級或自動甚至 模塊，使用自動指令成員選項， 像

.. automodule :: IO：成員：車博士需要，以便提取文檔字符串導入模塊 。因此，您必須在您的conf.py中將 適當的路徑添加到sys.path中。

將您的代碼模塊添加到列表中，然後致電make html來構建您的文檔並使用Web瀏覽器查看它。

進行一些更改，然後再次運行make html。

如果有使用sphinx-apidoc那麼我會建議：

1. 把你的教程在一個單獨的目錄.rst文件和
2. 引用從API文檔從在其中加上產生的文檔
3. 在您想要說明的地方引用代碼註釋中的教程。

這應該允許您根據您所做更改的位置分別構建教程和API文檔，並且它們之間仍有聯繫。

我會強烈提出以下建議：

• 使用版本控制系統，如水銀或git的，這樣就可以運行獅身人面像之前提交更改，
• 把你的教程.rst VCS下的文件，但不包含生成的文檔文件。
• 將所有的教程文件放在一個明確名稱的獨立目錄下，例如教程。
• 如果您要提供文檔，請爲生成的文檔使用單獨的存儲庫，用於存儲交付。
• 總是生成文件到一個位置外部你的代碼樹。
• 將sphinx-apidoc的調用放入批處理文件或make文件中，以便與您使用的設置保持一致。