有條件編譯Sphinx中的文檔部分

Question

我們正在計劃爲我們的軟件項目創建用戶手冊。目前，與代碼相關的所有內容都記錄在Sphinx中，我們希望使用Sphinx作爲手冊。

因爲我們正在編寫科學/工程軟件，會有很多像應力，應變，數值算法等的東西對於每個主題的主題，我們將擁有的信息中幾個階段：

1. 基本信息：這個一兩句話描述可以用在任何我們需要的話題的簡短摘要。例如：機械應力的簡單定義。
2. 更詳細的描述：這一段落的解釋可以用作幫助頁面的開頭，或更詳細的主題列表中的摘要。例如，關於引入軸嚮應力方程的機械應力段落。
3. 技術信息。關於該主題如何適用於我們軟件用戶遇到的問題，這可以是多段。
4. 代碼信息。這將是代碼中遇到主題的相關文檔。例如，我們可以指向我們的某個數值算法的實現。我們可以像我們目前那樣使用sphinx-apidoc。

正如你所看到的，信息逐漸變得更加複雜。我們希望在他們自己的.rst文件中管理每個主題，並根據需要獲取所需的信息。例如，也許我們想在工具提示中使用基本信息部分。在實際的幫助菜單中，我們可以在特定類別主題的目錄中使用詳細說明。在關於該主題的完整文章中，就像完整的pdf手冊中的內容一樣，我們可以提供技術信息以及基本和更詳細的說明。最後，我們希望僅將代碼信息保存在我們的內部文檔中。

將單個主題的所有信息保存在一個文件中，但根據我們生成的文檔有條件地編譯不同的部分將是很好的。

在Sphinx中是否有內置的方法來做這樣的事情？如果有人正在做類似的事情，你能告訴我們嗎？給我們一些工作流程的亮點？

Answer 1

在過去，我想編譯兩個文檔，公共和私人，但我不想分割我的源文件（rst）。

第一步我找到了only指令，我認爲這是解決方案。但是當我需要公開或私人文檔中的完整第一個文件時，我不能不縮進整個文件。

所以我寫我自己的獅身人面像插件（範圍）來管理我所有的情況。爲了成功，我使用了meta指令，它可以放在文件的頂部。

因此

a_doc_for_basic.rst

.. meta:: 
    :scope: basic 

Title 
===== 

My content 

a_doc_for_code。首先

.. meta:: 
    :scope: code 

Title 
===== 

My content 

而且你可以繼續在文件中使用.. only::指令

a_doc_for_all.rst

Title 
===== 

My content 

.. only:: code 

    a piece of code 

你可以找到插件的源here

正如你所看到的插件非常簡單，並得益於正則表達式。這意味着（正則表達式）有限制：

• 該指令.. meta:: :scope:必須在文件的頂部位置（無前行）
• 該指令.. meta:: :scope:必須在正則表達式^\.\. meta::\s+:scope: ([a-zA-Z0-9_-]+)
• 該指令匹配.. meta:: :scope:可以管理多個標籤但你可以很容易地更新您需要的插件
• 插件偏離原來使用meta指令docutils.sourceforge.net/docs/ref/rst/directives.html#meta的

那之後，你可以使用下面的命令

sphinx-build ... -t <tag> ... 

sphinx-build ... -t code ... 

其他東西建立你的文檔，你可以使用所有tag相同toctree因爲編譯每個標籤的文檔時，toctree將被編輯插件來生成樹，而不參考不匹配的文檔。

PS：我的插件並不完美，但我回復了我的需求，您可以啓發並更新它。