[CONF] Apache Sling Website: SlingDoc (page edited)

Tue, 07 Apr 2009 07:51:36 -0700

Page Edited : SLINGxSITE : SlingDoc

SlingDoc has been edited by Felix Meschberger (Apr 07, 2009).

(View changes)

Content:

Documenting Sling

The basic documentation of Sling is made up of four parts:

  1. The Sling Site at http://incubator.apache.org/sling (you are here)
  2. The Public Wiki at http://cwiki.apache.org/SLING
  3. The JavaDoc
  4. The Bundle documentation

This page is about how this documentation is maintained and who is allowed to do what.

The Sling Site

The Sling Site is maintained in the Confluence Wiki Space SLINGxSITE. The contents of this space is automatically synchronized with the web server with a simple shell script:

#!/bin/sh
#
# Synchronizes the Confluence Export of the
# Sling site to the site folder and fixes
# the mirror link settings of the downloads.html
# page which are incorrectly expanded to absolute
# links by the confluence export 

# Site folder
SITE=/www/incubator.apache.org/sling/site

# downloads page location
DLPAGE=${SITE}/downloads.html

# temporary copy of the downloads page
DLTMP=/home/fmeschbe/d.html 

# synchronized from Confluence export
/usr/local/bin/rsync -rt /www/confluence-exports/SLINGxSITE/ ${SITE}

# copy downloads page and replace with patched
cp ${DLPAGE} ${DLTMP}
cat ${DLTMP} | sed  's/http:\/\/cwiki.apache.org\/confluence\/display\/SLINGxSITE\/%5Bpreferred%5D/[preferred]/g' > ${DLPAGE}

# copy apache-sling.html to index.html
cp ${SITE}/apache-sling.html ${SITE}/index.html

which is called regularly as per the following crontab entry:

# sync wiki autoexport to Sling site
1 * * * * (/home/fmeschbe/sling.sh)

Thus, after editing the site source in the Wiki, the rest happens automatically, it just takes some time – in the order 2 hours or so – before the changes are visible at http://incubator.apache.org/sling.

Everybody is allowed to read the SLINGxSITE wiki and to add comments; but only committers of the Apache Sling project are allowed to edit the content and to manage the comments.

The Public Wiki

The public wiki of Sling is available at http://cwiki.apache.org/SLING and is maintained in the Confluence space SLING. This is a public wiki, in that after self-registration, everybody is allowed to edit content.

The JavaDoc

Up until now the JavaDoc of the Sling Bundles has not been published.

I just polished the JavaDoc generation setup of Sling a bit, so that I could generate a first shot of aggregate JavaDocs. This draft can currently be found on my site at http://people.apache.org/~fmeschbe/slingdocs.762729/. This JavaDoc has been generated as follows:

$ svn export -r 762729 http://svn.apache.org/repos/asf/incubator/sling/trunk sling
$ mvn -DexcludePackageNames="*.impl:*.internal:*.jsp:sun.misc:*.juli" org.apache.maven.plugins:maven-javadoc-plugin:2.5:aggregate

I am still unsure, whether it makes sense to generate aggregate JavaDoc for all (or part of) the bundles of Sling. See also below regarding the Sites.

The Bundle Documentation

Apart from the documentation of Sling on the Site and in the Wiki, it would also be thinkable, that we accompany the source modules with some documentation and generate this using the Maven Site plugin. My tests so far generating a multi-module site has not been very successfull. But generating the site in a module-by-module manner might be a good thing, at least to get the per-module JavaDoc and some more code-oriented information like Surefire Reports, fixed bugs, etc.

To prepare such Bundle Documentation I added a first shot at site generation setup to the parent project. For now, this includes the module's JavaDoc (of course), the Surefire reports and a report on the issues fixed (or open) with respect to some version. This site generation setup can be configured per module with two properties:

Property Description
site.jira.version.id The ID of the JIRA version whose bugs are to be listed in the JIRA report. This is a number, such as 12313306 (Sling API version 2.0.4).
site.javadoc.exclude The Java packages to not include with the JavaDoc generation. By default all packages containing impl or internal in their name are excluded. To add more packages for exlucsion, list them in the format suitable for the excludePackageNames property of the Maven JavaDoc plugin. For example, to exclude any jsp and juli packages (see the scripting/jsp bundle), this property would be set to .jsp:.juli.

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences

Reply via email to