始終重新生成包含特定指令的獅身人面像文件

獅身人面像通常會增量生成文檔，這意味着只有已更改的文件纔會重新生成。我想知道是否有辦法告訴獅身人面像總是重新生成某些文件，這些文件可能並未直接更改，但會受到其他文件更改的影響。更具體一點：有沒有辦法告訴Sphinx總是重新生成包含某個指令的文件？我正在處理的文檔依賴於通過指令相當頻繁地從其他頁面收集和重新格式化信息的可能性。乾淨（make clean && make [html]）和/或完整（sphinx-build -a）構建比增量構建花費的時間要長得多。此外，手動跟蹤包含該指令的文件可能會很複雜。該文檔由10多位撰寫Sphinx文檔的經驗不足的作者撰寫。始終重新生成包含特定指令的獅身人面像文件

但即使是在不太複雜的情況下，您可能會面對這個「問題」：例如sphinx.ext.todo含有一種叫todolist指令，它收集待辦事項從整個文檔。如果我從我的文檔（基本上只包含todolist指令的空文檔）創建一個包含所有待辦事項的文件，則在我進行清理構建或更改文件之前，列表不會更新。

如果你想測試它自己：與sphinx-quickstart創建一個文檔，並堅持爲默認值，除了

'> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y'

在source稱爲todos.rst從index.rst添加文件和參考文件。在index.rst的

內容：中todos.rst

Welcome to sphinx-todo's documentation! 
======================================= 

.. toctree:: 
    :maxdepth: 2 

    todos 


.. todo:: 
I have to do this 


Indices and tables 
================== 

* :ref:`genindex` 
* :ref:`modindex` 
* :ref:`search`

內容：

.. _`todos`: 

List of ToDos 
============= 

.. todolist::

假設你使用html輸出，你會發現，當你添加待辦事項到index.htmltodos.html不會改變。

TL;博士：如何 - 如果可能的話 - 我包括含有特定指令（例如todolist）爲增量構建獅身人面像，而無需手動跟蹤他們的文件？

來源

2017-06-26 aleneum

默認情況下，Sphinx只會更新新文件或更改文件的輸出。這是埋在sphinx-build -a。

在命令選項文件的結尾sphinx-build：

你也可以給在命令行中的一個或多個文件名的來源後，並建立目錄。然後Sphinx將嘗試構建僅這些輸出文件（及其依賴項）。

您可以直接或通過makefile調用sphinx-build，具體取決於Sphinx版本隨附的生成文件（您也可以自定義生成文件）。

來源

2017-06-26 11:12:04

謝謝你的回答。您的回答支持我目前的印象，即您必須創建所有內容或直接指定要重建的文件。我希望爲指令/文件或一些最佳實踐預處理（例如before-build-hook）提供一個整潔的隱藏的「白名單」關鍵字，但似乎並不存在。 – aleneum

只是爲了記錄：我基準了幾個解決方案。

我在我的conf.py中創建了一個叫做touch_files的函數。它搜索字符串的文件和 - 如果發現 - 觸摸文件來觸發重建：

def touch_files(*args): 
    # recursively search the 'source' directory 
    for root, dirnames, filenames in os.walk('.'): 
     # check all rst files 
     for filename in fnmatch.filter(filenames, '*.rst'): 
      cur = os.path.join(root, filename) 
      f = open(cur) 
      # access content directly from disk 
      s = mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ) 
      if any(s.find(d) != -1 for d in args): 
       # if a string pattern has been found alter the edit 
       # time of the file 
       os.utime(cur, None) 
      f.close() 

# actually call the function 
touch_files('.. todolist::')

touch_files可以用的參數變量量被調用，可以編輯文件時的論點之一是找到。我試圖用正則表達式優化函數，但是這並沒有達到很多。直接從磁盤讀取文件內容mmap似乎影響不大。

這是總共78個文件的結果，其中36個文件包含兩個指令之一。

Command         Time  Comment 
time make html       2.3 s No changes 
time sh -c 'make clean && make html' 13.3 s 
time make htmlfull      9.4 s sphinx-build -a  
time make html       8.4 s with 'touch_files' 
'touch_files'       0.2 s tested with testit

結果：每個命令都被稱爲短短的時間（除了「touch_files」），因此缺乏統計的可靠性。獅身人面像需要大約2.3秒的時間來檢查文件的變化而不做任何事情。一個乾淨的構建需要13.3秒，比sphinx-build -a的構建要長得多。如果我們只重建了78個文件中的36個，構建過程稍微快一點，但我懷疑這裏可以找到顯着差異。 'touch_files'的開銷很小。與編輯時間戳相比，查找字符串相當便宜。

結論：由於Steve Piercy指出，使用sphinx-build -a似乎是最合理的方法。至少在我的用例中。如果一個不包含指令的文件導致建設時間過長，那麼touch_files可能會很有用。

來源

2017-06-27 09:37:37 aleneum

始終重新生成包含特定指令的獅身人面像文件

回答

相關問題