Hey Paul,
thanks for putting effort on linearizing the documentation process. A
more than needed ECM effort :)
Below my comments on the process: I might be missing some details,
but I believe we could leverage better the standard documentation
tools from maven.
On May 2, 2010, at 11:33 PM, Goetz, Paul wrote:
Hi,
with regards to the documentation: you might have a look at http://people.apache.org/~pgoetz/chemistry
.
There's a first proposal how we could build the documentation.
But as always, there are some open questions:
- Is the proposed process ok for everyone? Any changes / suggestions?
As per step 1: isn't the site at http://incubator.apache.org/
chemistry/ just a plain empty generated "mvn site" with generic info
about the project? Why we need to wget it when we can easily
regenerate it as part of the mvn site process (step 6/7 in your
process)?
- For Step [7]: I'd assume that we will use the Maven Site info for
OpenCMIS. I wouldn't expect other (Non-Java) subprojects (cmislib,
JS-Client) to generate a Maven Site - so would one site be
sufficient (vs. every subproject having its own site)?
Agreed. Also for documentation deployment, can't we just use maven
site deployment [1] with SSH target repository, instead of using
rsync / rcp? This can all be run by Hudson, by the means of a 'mvn
site-deploy'.
- For Step [10]: We could either do some magic transformation (like
HTML Tidy + removing some sections like <style.../style>|<script.../
script>|<div class="greynavbar".../div>|<div class="footer".../div>,
and then apply the style sheets) - or we could change the template
for the CMIS site in Confluence (like CXF). Is there someone
experienced with Confluence templates?
Doxia, the Maven site engine, supports Confluence markup source pages
[2], so we could do an initial import of confluence markup pages in
SVN and have them neatly built by mvn (centralizing all documentation
efforts in Maven from that point on).
I can try to spike this in the next days, to basically streamline a
process where:
- Current Confluence pages are added to SVN and then build by maven
- Current project information at incubator.apache.org/chemistry is
regenerated by the mvn build
1. New pages are added in any of the mvn site supported input formats
[3] (BTW, you could also develop pages as drafts on Confluence first,
and then add them to SVN when wanting to aggregate them to the
"official" site)
2. Site is deployed by hudson by mvn site-deploy, possibly by a
specific build plan on a different schedule
This approach definitely still needs to be tested, but I believe it
can take off some maintenance burden and get us up to speed on this
topic.
Am I missing something (I guess) ? :)
If nobody objects, I would continue with the following todos:
1) initial check-in for website content to SVN [4]
2) add cronjob to do the SVN update for the website [3]
3) update OpenCMIS Maven site content and check-in to SVN [5]
4) add cronjob or Hudson task to replicate OpenCMIS' Maven site
target build to /www/incubator.apache.org/chemistry/site.opencmis [7]
5) change the template for CMIS in Confluence
6) add cronjob to copy /www/confluence_export/CMIS to /www/
incubator.apache.org/chemistry/wiki
Best regards,
Paul
As I said I'm happy to help on this, as I've been working on mvn doc
sites quite extensively in the past and it might get tricky to do the
configuration bits.
Could start by adding a visual of the process here [4] , if you guys
believe it's a valid option.
WDYT?
Ciao,
Gab
[1] http://maven.apache.org/plugins/maven-site-plugin/deploy-mojo.html
[2] http://maven.apache.org/doxia/doxia/doxia-modules/doxia-module-confluence/
[3]
http://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html
[4] http://people.apache.org/~pgoetz/chemistry/
-----Original Message-----
From: David Caruana [mailto:[email protected]]
Sent: Freitag, 30. April 2010 10:22
To: [email protected]
Subject: Re: OpenCMIS release check list
---8<---
- web site update (as source of the documentation to be
packaged) ... not started yet
I can now confirm that Alfresco can provide someone to design/
provide a skin for the web site.
--->8---
--
Eng. Gabriele Columbro
Alfresco Software, Ltd.
M: +31 (0)627 565 103
P: +39 320 161 28 46
D: +44 (0)1628 876 654
Skype: gabrielecolumbro
Blog: http://www.mindthegab.com
