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

Question

我正在开发一个正在获得越来越多版本的小玩具项目。到目前为止，文档只是我为项目设置的wordpress博客中的一组页面。但是，随着时间的推移，新版本已经发布，我应该更新在线文档以匹配最新版本。

不幸的是，如果我这样做，之前版本的文档将“消失”，因为我的文档页面已更新到最新版本，因此我决定将文档包含在发布包和也可以将最新文档作为网页在线提供。

一个简单的想法是从wordpress页面中获取当前文档，将它们保存到svn中，然后保存到发布包中，在每个新版本中重复该过程。不幸的是，我得到的HTML必须手工修复以修复链接（或者我应该破解wordpress以使用BASE，以便HTML代码可以轻松重定位，这是我不想做的事情。）

我应该如何处理同时出现的要求：

1. 可下载软件包中包含的正确版本的用户可浏览文档
2. 最近在线提供的文档（并使用我的网络主题进行了适当的设置）
3. 在svn和实际在线内容之间保持同步（在wordpress中，或其他适合我的wordpress设置的内容）
4. 易于使用

由于

编辑：开始赏金，看看我是否能引出更多答案。我认为这是一个非常重要的问题，为未来的读者提供多种提示和意见会很好。

Answer 1

我会将您的页面检查到SVN，然后在您准备发布时从其本地SVN工作副本更新您的网站服务器。把所有东西都放到SVN中 - wordpress，CSS，HTML等。

Answer 2

WGet可以为您转换文档中的所有链接。请参阅convert-links选项：

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

与其他方法结合使用可以产生解决方案。

Answer 3

我见过一些程序使用help & manual。但我是Mac用户，我没有经验，知道它是否有用。我正在为Mac寻找解决方案。

Answer 4

对于我自己的项目，如果需要，我会为文档创建一个子目录，并且所有文件都来自相对的已知基础。例如，

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中（例如docs / v1.05 /）

它是一个简单的PHP脚本，可以编写该列表以从本地磁盘获取/ docs /目录的子目录并显示列表，并突出显示最新的列表，例如。

Answer 5

我认为这里有两个问题需要解决

1. 如何以及在何处使文档与代码保持一致
2. 在哪里发布文档

对于1我认为最好：

• 将文档保存在存储库（SVN或git或您已经用于代码的任何内容）作为一组文件，而不是在数据库中，因为它更容易保留更改历史记录（可能保持不变使用代码发布
• 使用一种方法，其中文档是从一组源文件（您将源保存在存储库中）生成的，从中生成分发包的html文件或在Web上发布。这两者可能会有所不同，因为在网络上，您需要保留一些版本信息（在URL中），这些信息在打包单个版本时不需要。

要做“2”，有几个工具可能会生成静态网站。其中一个是Jekyll它是红宝石，看起来非常完整和可定制。

假设您使用像jekyll这样的工具并将文件和源保存在SVN中，您可以这样设置您的仓库：

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

那是：

• 您将当前文档保留在主干
中的源旁边
• 当您执行发布时，您将为该版本创建一个标记
• 您配置文档生成器以生成每个repo / tags //文档目录的文档，以便每个版本的文档放在documentation_site /目录中

所以要发布文档（上面第2点）：

• 您在服务器上复制documentation_site目录的内容，将其放在wordpress安装的相同基础目录或从中进行链接，以便每个发布文档都可以访问：http://yoursite/project/docs/relXX/
• 您创建了指向当前版本文档的链接，以便始终可以http://yoursite/project/docs/current
访问它

这里的技巧是始终在适当的发布标识符（在URL中，在文件系统上）发布文档，并使用链接（或重定向）来确保Web服务器上的“当前文档”指向当前版本。