creadur-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <seb...@gmail.com>
Subject Re: Switch to CMS ... ?
Date Mon, 07 May 2012 02:31:00 GMT
On 6 May 2012 19:45, Robert Burrell Donkin <rdonkin@apache.org> wrote:
> On 05/06/12 16:04, sebb wrote:
>>
>> On 6 May 2012 13:52, Robert Burrell Donkin<rdonkin@apache.org>  wrote:
>>>
>>> The next stage of the graduation hand-over is setting up the
>>> infrastructure
>>> for Apache Creadur TLP. This includes the website.
>>>
>>>
>>> I think there's generally positive feelings about the CMS, excepting
>>> committing Maven generated sites. As a user, I find the Maven sites for
>>> releases are useful. So, I suggest switching to the CMS and dropping the
>>> Maven sites for anything other than releases.
>>
>>
>> Not sure what you mean by that.
>
>
> (I'm still trying - and failing - to be meaningful and concise...)
>
>
>> How can there be a CMS site and a separate Maven site?
>> What URLs will these be using?
>
>
> We were experimenting [1] with checking in Maven sites...
>
> Checking generated Maven sites into the CMS (eg [2]) produces lots of commit
> messages (eg [3]), and is a little fiddly.

AFAICT, most of the commit message flood at [3] is because Javadoc
embeds a timestamp comment in the generated output.
I don't think that is entirely Maven's fault, though of course Maven
does not support rebuilding only the changed part of a site.

[Unfortunately using -Dmaven.javadoc.skip does not quite work, as
Maven creates an empty apidocs/index.html file]

I had the same problem with JMeter Javadoc when it was in SVN; I
solved that by post-processing the html files to remove the dates in
the comments.
The same could probably be done in the Maven pom if required.

>
> [1]
> http://mail-archives.apache.org/mod_mbox/incubator-rat-dev/201204.mbox/%3C4F8037FE.7050302%40blueyonder.co.uk%3E
> [2] http://rat.staging.apache.org/rat/rat/
> [3]
> http://mail-archives.apache.org/mod_mbox/incubator-rat-commits/201204.mbox/%3C20120407124344.BB6C523889BB%40eris.apache.org%3E
>
>
>>> If we're going to switch to the CMS, it will save some effort if we ask
>>> infrastructure to set it up for the new TLP domain.
>>>
>>> Opinions? Objections?
>>
>>
>> I think the CMS works well for sites that need frequent updates of
>> parts of the site.
>> For example, the main ASF site.
>>
>> Conversion to Markdown format can be a non-trivial exercise; although
>> there are some scripts, their output still needs some tweaking.
>> And there are some features of HTML which are not directly supported
>> by Markdown (e.g. numbered lists using alpha).
>>
>> For Maven sites that are generally only updated with each new release,
>> the fact that Maven sites cannot be built piecemeal is not an issue,
>> so is it worth the conversion effort?
>
>
> Rat is sparsely documented, but I had hoped to work on some new,
> user-centered content in the CMS and leave the existing stuff for releases.

Unless it is going to change much between releases, it could still be
done by Maven at release time.

However, there might be some restrictions imposed by CMS or Infra as
to which URLs can be used for Maven and non-Maven generated site
files.

Might be an idea to run the plan past infra before doing much work.

> We need some form of cohesive top level site for Apache Creadur, hopefully
> with some more documentation for users. The consensus seemed to be that
> using the CMS fits this well, and allows some products to use Maven and some
> to use the CMS for their documentation (by checking the Maven generated
> sites into CMS).

For new content, CMS is probably a good choice.

> Having tried it for a while, never me nor Stefan are particular keen[1]
> about regularly checking in Maven generated sites. I'd be happy just
> checking in the Maven generated documentation for each release.

Indeed, Maven-generated sites are best suited for release time docs.

> Robert
>
> [1]
> http://mail-archives.apache.org/mod_mbox/incubator-rat-dev/201204.mbox/%3C87lim5las5.fsf%40v35516.1blu.de%3E

Mime
View raw message