eZ Community » Blogs » Community Project Board » It's that time of the year again......

By

It's that time of the year again... when a revamp of eZ documentation on pubsvn is under way

Monday 07 November 2011 10:28:42 pm

  • Currently 3 out of 5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

On http://pubsvn.ez.no, developers can find automatically-generated documentation of the php-level API for the current version of eZ Publish - and for many historic versions too.

With the exponential growth of versions due to the monthly release schedule, it's time to think again at what documentation to build and how. Read on for a proposal...

Current Situation:

  • the http://pubsvn.ez.no server is building nightly docs of many code branches. Most of them are in a kind of "deep freeze" mode, with very little to no git activity (4.0 to 4.4, so it makes little sense to re build those docs every night
  • even if there was a commit tomorrow for the 4.4 branch, most users reading the doc will probably not deploy the new code anyway, but keep using the "stable" version. Hence what they want is not the "daily doc for 4.4 branch", but "doc for 4.4 version" 
  • we still miss docs for version 4.5, which was never tagged on github
  • we miss docs for the ezp-next api (it's in a separate github repo)

Proposal:

  • for all releases, build the doc only once, not daily. Build it from an actual tarball instead of git (to overcome problem of missing tags and just in case there is any difference)
  • only build doc daily for "trunk" branch
  • add ezp-next to the available docs (daily, from trunk)
  • we currently use 3 tools for generating documentation: doxygen, docblox, phpdocumentor. The latter is considered abandonware, and does not support many php 5 goodies (eg. namespaces). Let's abandon it, at least for daily builds and for new releases, and keep it only for historical releases.

Comments are, as always, wlecome

Proudly Developed with from