CODEWITHSUNDEEP
documentationdocumentation-generation
Stefano Borini
Stefano Borini

Reputation: 143795

How to keep synchronized, per-version documentation?

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.

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).

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

  1. user-browsable documentation for the proper version included in the downloadable package
  2. most recent documentation available online (and properly styled with my web theme)
  3. keep synchronized between the svn and the actual online contents (in wordpress, or something else that fits nicely with my wordpress setup)
  4. 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.

Upvotes: 1

Views: 645

Answers (5)

LucaM
LucaM

Reputation: 2846

I think there are two problems to be solved here

  1. how and where to keep the documentation aligned with the code
  2. 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.

Upvotes: 1

Pablojim
Pablojim

Reputation: 8582

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

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

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

Upvotes: 2

Alister Bulman
Alister Bulman

Reputation: 35149

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.

Upvotes: 1

neoneye
neoneye

Reputation: 52201

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.

Upvotes: 1

i_am_jorf
i_am_jorf

Reputation: 54600

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.

Upvotes: 2

Related Questions