I guess something like that would work, although it would be nice if in
addition to that we packaged the documentation with the release itself.
The requirement is simple, we need to make the documentation for
previous releases available in an easy to access location - for example
take a look at how Maven does it [1]. Maven also uses a static URL to
refer to the current version of the docs [2] which I think is important
also. However we achieve that I don't mind, so whether we copy it to
another place, or tag it as part of the release process or whatever.
[1] http://maven.apache.org/ref/
[2] http://maven.apache.org/ref/current/
Shane
On 25/07/12 18:20, Romain Manni-Bucau wrote:
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
