1

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

不幸的是，如果我这样做了，以前版本的文档将“消失”，因为我的文档页面已更新到最新版本，因此我决定将文档包含在发布包中，并将最新的文档在线保留为一个网页也是如此。

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

我应该如何处理同时拥有的要求：

  1. 可下载包中包含的正确版本的用户可浏览文档
  2. 在线提供的最新文档（并与我的网络主题正确样式）
  3. 在 svn 和实际在线内容之间保持同步（在 wordpress 中，或其他与我的 wordpress 设置非常吻合的东西）
  4. 便于使用

谢谢

编辑：开始赏金，看看我是否能引诱更多答案。我认为这是一个相当重要的问题，如果能给未来的读者多点提示和意见，那就太好了。

4

5 回答 5

2

我会将您的页面检查到 SVN 中，然后在您准备发布时从其本地 SVN 工作副本更新您的网络服务器。将所有内容放入 SVN——wordpress、CSS、HTML 等。

于 2009-06-13T17:17:02.853 回答
2

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

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

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

于 2009-06-15T22:19:26.543 回答
1

我见过一些程序使用帮助和手册。但我是 Mac 用户，我没有使用它的经验，不知道它是否有任何好处。我正在为 Mac 自己寻找解决方案。

于 2009-06-13T17:17:55.427 回答
1

对于我自己的项目，如果需要的话，我会为文档创建一个子目录，并让所有文件相对地从那里的已知库中引用。例如，

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 下载中，则它们可以按原样阅读。如果它们是从一些原始文件生成的，它们将被预先生成为一个可下载的版本。

文档的存档版本可以解压缩/生成并放入命名目录（例如 docs/v1.05/）

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

于 2009-06-13T18:44:41.020 回答
1

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

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

对于 1，我认为最好：

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

要做到“2”，有几个工具可以生成静态站点。其中之一是Jekyll，它是 ruby​​ 的，看起来非常完整和可定制。

假设您使用像 jekyll 这样的工具并将文件和源代码保存在 SVN 中，您可能会以这种方式设置您的 repo：

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

那是：

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

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

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

于 2009-06-17T12:54:58.187 回答