Just by curiosity, what do you expect as version management? Kind of tool where you say "ok doc for vX is done copy it in another place"?
- Romain 2012/7/25 Shane Bryzak <[email protected]> > Yes, I saw the e-mail with subject "CMS area in SVN" on 2 June but it > didn't occur to me that this was for documentation (I thought it was just > for the web site). Also, Jason attempted twice (both in the mailing list > and in DELTASPIKE-13) to start a discussion on documentation format and > no-one responded. > > I honestly don't mind which documentation format we use, however before we > go any further I want to ensure that the tools that have been chosen > support the requirements that I listed earlier. David's description of the > CMS is helpful, but I just want to identify that we still have missing gaps > in terms of versioned-per-release documentation and downloadable > documentation in alternative formats. From the sound of it, these things > both appear possible if we are using Apache CMS, however it seems we need > to do some extra work with the documentation directory structure for the > versioning side of things, and with the release process for > tagging/packaging the documentation. If others are in agreement, we should > probably create JIRA issues to track these tasks. > > Shane > > > On 25/07/12 16:17, Mark Struberg wrote: > >> David, the CMS is already set up and running (in SVN [1]). We just need a >> bit more stylish css. >> >> And you can perfectly create pdf docs out of markdown. >> >> Of course we can also use alternative formats. But to me this is like a >> colour preference - markdown is supported out of the box and provides all >> needed options. >> >> Shane, I don't think I bypassed anyone. We discussed this since 6 months >> and noone started working on it. Thus I finally dropped a mail and then >> implemented it. I also got no stop mail back then. >> Honestly I really don't care which format we use, IF someone else is >> doing the work and others can easily add documentation. >> >> >> LieGrue, >> strub >> >> >> >> [1] >> http://svn.apache.org/repos/**asf/incubator/deltaspike/site/**trunk/<http://svn.apache.org/repos/asf/incubator/deltaspike/site/trunk/> >> >> >> >> ----- Original Message ----- >> >>> From: David Blevins <[email protected]> >>> To: >>> deltaspike-dev@incubator.**apache.org<[email protected]> >>> Cc: Mark Struberg <[email protected]> >>> Sent: Wednesday, July 25, 2012 2:37 AM >>> Subject: Re: [suggestion] - Documentation >>> >>> T he answer to both these questions really that the CMS creates >>> "websites", some details on that below >>> >>> I'll note that the CMS is svn based -- maybe undesirable given the use of >>> git. >>> >>> On Jul 24, 2012, at 4:54 PM, Shane Bryzak wrote: >>> >>> Does the choice of Apache CMS for hosting documentation meet the >>>> following >>>> >>> requirements? >>> >>>> 1) Making available the documentation for previously released >>>> versions of >>>> >>> DeltaSpike. >>> >>> If by "make available" the intention is browsable on the website, then >>> sure there are ways to handle that. >>> >>> 2) Making available the documentation in offline formats, such as >>>> HTML or >>>> >>> PDF available for download. >>> >>> Certainly you can use the same source to generate non-website looking >>> HTML. >>> Same goes for PDF. >>> >>> You wouldn't be using the CMS to do this, but the CMS doesn't prevent >>> it. It'd be something we setup ourselves and could be done via a CI >>> server >>> or something done at release time. >>> >>> Basically the CMS is a system that is for generate website html using the >>> following layout: >>> >>> - content/<source-files-and-**directories> >>> - lib/<site-generating-perl-**functions> >>> - templates/<whatever-you-need-**for-templates> >>> >>> When something in 'content/' is updated, it will run it through lib/ >>> (which leverages templates/) and save the resulting html to disk and >>> take care >>> of synching that html file from staging to production. >>> >>> When something in 'lib/' or 'templates/' is updated, it pretends >>> as if everything in 'content/' has changed and performs the above step >>> on every source file. >>> >>> You can organize the 'content/' dir however you want. That could mean: >>> >>> - content/v0.1/ >>> - content/v0.2/ >>> - content/current/ >>> >>> Where 'current' gets versioned on release. Or anything at all. Maybe >>> just: >>> >>> - content/<wild-wild-west> >>> >>> >>> So the short answer is there isn't anything there to prevent or help the >>> two >>> points. >>> >>> In terms of generating outside the CMS which is what would be needed for >>> say, >>> turning many files into one file such as a zip of html or a PDF, it's up >>> to >>> us. There are projects that do it via buildbot. Buildbot is not so >>> much a CI >>> tool as it is "cron with a webUI" and also happens to have the ability >>> to be trigger by commits. >>> >>> Really, you can get anything done with buildbot without much in the way >>> of >>> restrictions. It's a mediocre CI system and an amazing cron replacement. >>> >>> >>> -David >>> >>> > >
