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

I am working on a small toy project who is getting more and more releases. Until now, the documentation was just a set of pages in the wordpress blog I setup for the project. However, as time passes, new releases are out and I should update the online documentation to match the most recent release.

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

Unfortunately, if I do so, the docs for the previous releases will "disappear" as my doc pages are updated to the most recent version, therefore I decided to include the documentation in the release package and to keep the most recent documentation available online as a web page as well.

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

A trivial idea would be to wget the current docs from the wordpress pages, save them into the svn and therefore into the release package, repeating the procedure at every new release. Unfortunately, the HTML I get must be hacked by hand to fix the links (or I should hack wordpress to use BASE so that the HTML code is easily relocatable, something I don't want to do).

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

How should I handle the requirements of having at the same time:

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

user-browsable documentation for the proper version included in the downloadable package

可下载软件包中包含的正确版本的用户可浏览文档

most recent documentation available online (and properly styled with my web theme)

最近在线提供的文档(并使用我的网页主题进行了适当的样式设置)

keep synchronized between the svn and the actual online contents (in wordpress, or something else that fits nicely with my wordpress setup)

在svn和实际的在线内容之间保持同步(在wordpress中,或者与我的wordpress设置非常吻合的其他内容)

easy to use

使用方便

Thanks

Edit: started a bounty to see if I can lure more answers. I think this is a quite important issue, and it would be nice to have multiple hints and opinions for future readers.

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

5 个解决方案

#1

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:

对于1我认为最好:

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

将文档保存在存储库(SVN或git或您已经用于代码的任何内容)作为一组文件,而不是在数据库中,因为它更容易保留更改历史记录(可能与代码保持一致)发布

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.

使用一种方法,其中文档是从一组源文件(您将源保存在存储库中)生成的,从中生成分发包的html文件或在Web上发布。这两者可能会有所不同,因为在网络上,您需要保留打包单个版本时不需要的一些版本信息(在URL中)。

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.

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

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

假设你使用像jekyll这样的工具并保留SVN中的文件和源代码,你可以用这种方式设置你的repo:

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

配置文档生成器以生成每个repo / tags //文档目录的文档,以便将每个版本的文档放在documentation_site /目录中

So to publish the documentation (point 2 above):

所以要发布文档(上面的第2点):

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/

您在服务器上复制documentation_site目录的内容,将其放在wordpress安装的相同基础目录或从中链接,以便每个发布文档可以访问: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

您可以创建指向当前发行版文档的链接,以便始终以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.

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

#2

I would check your pages into SVN, and then have your webserver update from its local SVN working copy when you're ready to release. Put everything into SVN--wordpress, CSS, HTML, etc.

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

#3

WGet can convert all the links in the document for you. See the convert-links option:

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

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

Using this in conjuction with the other methods could yield a solution.

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

#4

I have seen some programs use help & manual. But I am a Mac user and I have no experience with it to know if it's any good. I'm looking for a solution myself for Mac.

我见过一些程序使用帮助和手册。但我是Mac用户,我没有经验,知道它是否有用。我正在为Mac寻找解决方案。

#5

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.

如果文档包含在SVN / tarball下载中,那么它们就是可读的。如果它们是从某些原始文件生成的,则会为可下载版本预先生成它们。

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

可以解压缩/生成文档的存档版本并将其放入命名的directorys中(例如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.

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

#1