Apache
Home
This page is a translated version of /site/documentation.html. In case of doubt you might want to refer to the old page.

Documentation

The documentation is split into different parts:

How can you contribute

We're on the way to improve the documentation, but it's a long way. If you would like to contribute to the documentation you are very welcome. Please directly post your proposals to the public wiki or post your suggestions to the mailing list.

How is the documentation generated

The Sling web site and documentation are managed with the Apache CMS. For Apache Sling specific extensions see the The Sling Site section below.

The Sling site is being converted from a Confluence exported site to an Apache CMS managed site. During this conversion not all pages will display correctly. All non-fully converted pages will show a tip box pointing to the original Confluence exported page for reference.

Once migration of a page has completed the translation_pending header should be removed from the page source. After that the tip box will not be shown any more.

While this page has technically been translated already, the translation-pending header is kept to remind us to remove this info box once translation has completed.

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

  1. The Sling Site at http://sling.apache.org/ (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 site is managed with the Apache CMS where the source is kept in SVN at https://svn.apache.org/repos/asf/sling/site/trunk/content.

This section lists some Apache Sling features to help with the maintenance of the site, such as automatic link generation.

Start the file with a Title: line to define the page title and the first H1 tag:

Title: Page Title

Here comes the content separated with a blank like from the
header ...

The last modification information from SVN (revision, committer, and date/time) is automatically added when the page is rendered

Excerpts can be added to a page using the Excerpt: header:

Title: Page Title
Excerpt: Summary of the page for inclusion in other pages;
   continuation of the excerpt must be indented

Here comes the content separated with a blank like from the
header ...

Metadata from child pages can be referred to in the content with the Django variable reference notation using the child page name (without extension) as its container; e.g. for the child page named childpage:

{{ children.childpage.headers.excerpt }}
{{ children.childpage.headers.title }}

Content Pages can contain Django templates of the form {{...}} and {%...%}. If so, the page content is evaluated as a Django template before running it through the page template.

Any page in the site can be referenced with refs.pagename returning properties:

.path
the absolute path of the page on the site
.headers
page headers (e.g. .title, .excerpt)
.content
the raw page content

All pages in the children namespace are also available in the refs namespace

Some usefull hints:

Printing title of another page "handler":

   :::django
   {{ refs.handler.headers.title }}

Printing excerpt of another page "handler":

   :::django
   {{ refs.handler.headers.excerpt }}

Linking to another page "handler":

   :::django
   ({{ refs.handler.path }})

Printing title as a link to another page "handler":

   :::django
   [{{ refs.handler.headers.title }}]({{ refs.handler.path }})

Printing excerpt as a link to another page "handler":

   :::django
   [{{ refs.handler.headers.excerpt }}]({{ refs.handler.path }})

Print a bullet pointed child page list:

   :::django
   {% for label, page in children %}* [{{ page.headers.title }}]({{ page.path }})
   {% endfor %}
It is important to have the first part as a single line, otherwise the Django/Markdown combo will create a list for each entry.

Code Highlighting

Code Highlighting works by indenting code by four blanks. To indicate the type of highlighting preced the code style text with either :::<lexer> to get high lighted code using the given <lexer> or #!<lexer> to get high lighted code with line numbers using the given <lexer>. See http://www.apache.org/dev/cmsref.html#code-hilighter for main info and http://pygments.org/docs/lexers/ for supported lexers

Manual Generation

When commiting changes to pages into SVN the pages are automatically generated in the staging site.

To manually generate the site or single pages the site can be checked out from SVN. In addition Perl and Python must be installed for the build tools to work.

To prepare for site build, the Markdown daemon has to be started:

$ export MARKDOWN_SOCKET="$PWD/tools/build/../markdown.socket"
$ export PYTHONPATH="$PWD/tools/build"
$ python "$PWD/tools/build/markdownd.py"

The MARKDOWN_SOCKET environment variables is also required by the build_site.pl and build_file.pl scripts to connect to the Markdown daemon.

To build the complete site use the build_site.pl script:

$ tools/build/build_site.pl --source-base $PWD/trunk \
    --target-base $PWD/trunk/target

To build a single page use the build_file.pl script:

$ tools/build/build_site.pl --source-base $PWD/trunk \
    --target-base $PWD/trunk/target \
    --source content/documentation.mdtext

The argument to the --source parameter is relative to the --source-base folder.

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 for generating a multi-module site have not been very successful. 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 exclusion, 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.
Rev. 1639357 by kwin on Thu, 13 Nov 2014 15:09:19 +0000
Apache Sling, Sling, Apache, the Apache feather logo, and the Apache Sling project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.