如何保持每版本文檔的同步？

我正在製作一個越來越多的小玩具項目。到目前爲止，文檔只是我爲項目設置的wordpress博客中的一組頁面。但是，隨着時間的流逝，新版本已經出來，我應該更新在線文檔以匹配最新版本。如何保持每版本文檔的同步？

不幸的是，如果我這樣做，對於以前的版本中將會「消失」作爲我的文檔頁面的文檔被更新到最新的版本，所以我決定在發佈包和文檔保持最新的文檔也可以作爲網頁在線提供。

一個簡單的想法是從wordpress頁面中獲取當前的文檔，將它們保存到svn中，並保存到發佈包中，然後在每個新發布的版本中重複該過程。不幸的是，我得到的HTML必須手動修復鏈接（或者我應該攻擊wordpress以使用BASE，以便HTML代碼易於重新定位，這是我不想做的）。

我應該如何處理在同一時間有要求：包括了正確的版本

用戶瀏覽的文檔中的下載包
最新文檔可在網上（與適當的風格我網絡主題）
保持SVN和實際的在線內容之間同步（在WordPress，還是其他什麼東西，與我的WordPress安裝非常適合）
使用方便

謝謝

編輯：開始了賞金，看看我能否引誘更多的答案。我認爲這是一個相當重要的問題，對未來的讀者有很多提示和意見會很好。

來源

2009-06-13 Stefano Borini

我覺得有兩個問題在這裏解決

在何處以及如何保持
要發佈的文件

對於1我認爲這是一個與代碼一致的文檔最好是：

將文檔保存在存儲庫（SVN或git或任何您已經使用過的對於代碼）爲一組文件，而不是在一個數據庫，因爲它是更容易保持變化的歷史（的可能留在齊名的代碼發佈
使用其中的一組生成的文檔的方法源文件（你會保持在存儲庫中源），從中產生的分發包或發佈在網絡上的HTML文件。這兩種可能可能不同，因爲在網絡上你需要保留一些版本信息（網址），其包裝的單一版本，當你不需要的東西。

要做「2」，有幾個工具可能會產生一個靜態網站。其中之一是Jekyll它在紅寶石，看起來相當完整和可定製的。

假設你使用像哲基爾的工具，並保持文件和源在SVN你可能會設置你的回購以這樣的方式

repo/ 
    tags/ 
     rel1.0/ 
     source/ 
     documentation/ 
     rel2.0/ 
     source/ 
     documentation/ 
     rel3.0/ 
     source/ 
     documentation/ 
    trunk/ 
     source/ 
     documentation/

即：

你保持當前的文檔在主幹旁邊的源文件中
當您執行發行版時，您爲發行版創建標籤
您將文檔發生器配置爲生成文檔entation爲每個回購/標籤//文檔目錄，使得每個版本的文檔放在documentation_site的/目錄

所以要發佈的文件（上述第2點）：

複製在服務器上documentation_site目錄的內容，把它在你的wordpress的相同的基本目錄安裝或從該鏈接，使得每個版本的文檔可以作爲訪問：http://yoursite/project/docs/relXX/
您創建一個鏈接到當前版本的文檔，例如它總是可以達到爲http://yoursite/project/docs/current

這裏的技巧是始終在正確的發佈標識符下（在URL中，在文件系統上）發佈文檔，並使用鏈接（或重定向）來確保Web上的「當前文檔」服務器指向當前版本。

來源

2009-06-17 12:54:58 LucaM

我會檢查你的頁面到SVN中，然後當你準備發佈時，從你本地的SVN工作副本上更新你的web服務器。把所有東西都放到SVN中 - wordpress，CSS，HTML等。

來源

2009-06-13 17:17:02

我已經看到一些程序使用help & manual。但我是Mac用戶，我沒有經驗知道它是否有用。我正在爲Mac尋找解決方案。

來源

2009-06-13 17:17:55 neoneye

對於我自己的項目，如果那是需要的話，我會爲文檔創建一個子目錄，並且所有文件都從相關的已知基礎引用。例如，

index.html -- refers to images/example.jpg 
README 
-- subdirs.... 
    images/example.jpg 
    section/index.html -- links back to '../index.html', 
         -- refers to ../images/example.jpg

如果文檔包含在SVN/tarball下載中，則它們可以按原樣讀取。如果它們是從一些原始文件生成的，則它們將爲可下載版本預先生成。

文檔的歸檔

版本可以解壓/生成並放置到名爲directorys（例如，文檔/ V1.05 /）

其可以寫入得到一個列表的子目錄一個簡單的PHP腳本/ docs /目錄，並顯示一個列表，並突出顯示最近的一個例子。

來源

2009-06-13 18:44:41

這或多或少是我可以做的，但事實是我必須破解wordpress才能使用base，然後從網上下載內容 – 2009-06-13 19:54:41

WGet可以爲您轉換文檔中的所有鏈接。見轉換鏈接選項：

http://www.gnu.org/software/wget/manual/html_node/Advanced-Usage.html

在同一起選擇其他方法使用，這可能產生一個解決方案。

來源

2009-06-15 22:19:26 Pablojim

如何保持每版本文檔的同步？

回答

相關問題