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

发布于 2024-07-23 10:12:35 字数 643 浏览 7 评论 0原文

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

不幸的是，如果我这样做，以前版本的文档将“消失”，因为我的文档页面已更新到最新版本，因此我决定将文档包含在发行包中和以保留最新的文档也可通过网页在线获取。

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

我应该如何处理以下要求：

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

谢谢

编辑：开始赏金，看看我是否可以吸引更多答案。我认为这是一个非常重要的问题，如果能为未来的读者提供多种提示和意见，那就太好了。

原文

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

荒芜了季节 2024-07-30 10:12:36

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

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

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

回复收藏 0 原文

回忆躺在深渊里 2024-07-30 10:12:36

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

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

对于 1，我认为最好：

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

要执行“2”，有多种工具可以生成静态站点，其中之一是 Jekyll 它是用 ruby 编写的，看起来非常完整且可定制。

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

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

：

将当前文档保留在主干中的源代码旁边
。发布时，
您配置文档生成器为每个 repo/tags//documentation 目录生成文档，以便每个版本的文档都放在 Documentation_site/ 目录中

因此，要发布文档（上面的第 2 点）：

您在服务器上复制Documentation_site 目录的内容，将其放在 WordPress 安装的同一基目录中或从该目录链接，以便可以通过以下方式访问每个发布文档： http://yoursite/project/docs/relXX/
您创建一个指向当前版本文档的链接，以便始终可以通过 http://yoursite/project/docs/current

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

I think there are two problems to be solved here

how and where to keep the documentation aligned with the code
where to publish the documentation

For 1 i think it's best to:

keep the documentation in a repository (SVN or git or whatever you already use for the code) as a set of files, instead of in a db as it is easier to keep a history of changes (an possibly to stay in par with the code releases
use an approach where the documentation is generated from a set of source files (you'd keep the sources in the repository) from which the html files for the distribution package or for publishing on the web are generated. The two could possibly differ, as on the web you'd need to keep some version information (in the URL) that you don't need when packaging a single release.

To do "2" there are several tools that may generate a static site. One of them is Jekyll it's in ruby and looks quite complete and customizable.

Assuming that you use a tool like jekyll and keep the files and source in SVN you might setup your repo in this way:

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

That is:

You keep the current documentation beside the source in the trunk
When you do a release you create a tag for the release
you configure your documentation generator to generate documentation for each of the repo/tags//documentation directory such that the documentation for each release is put in documentation_site/ directory

So to publish the documentation (point 2 above):

you copy on the server the contents of the documentation_site directory, putting it in the same base dir of your wordpress install or linking from that, such that each release doc can be accessed as: http://yoursite/project/docs/relXX/
you create a link to the current release documentation such that it can always be reached as http://yoursite/project/docs/current

The trick here is to publish the documentation always under a proper release identifier (in the URL, on the filesystem) and use a link (or a redirect) to make sure that the "current documentation" on the web server points to the current release.

回复收藏 0 原文

猫七 2024-07-30 10:12:36

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

回复收藏 0 原文

腹黑女流氓 2024-07-30 10:12:36

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

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/ 目录的子目录列表，并例如，显示列表并突出显示最新的列表。

For my own projects, if that were a need, I would create a sub-dir for the documentation, and have all the files refer from the known-base of there relatively. For example,

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

If the docs are included in the SVN/tarball download, then they are readable as-is. If they are generated from some original files, they would be pre-generated for a downloadable version.

Archive versions of the documentation can be unpacked/generated and placed into named directorys (eg docs/v1.05/)

Its a simple PHP script that can be written to get a list the subdirs of the /docs/ directory from the local disk and display a list, and highlighting the most recent, for example.

回复收藏 0 原文