incubator-sling-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Sling Website > Documentation
Date Fri, 13 Aug 2010 10:38:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=SLINGxSITE&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/Documentation">Documentation</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~aheimoz">Alison
Heimoz</a>
    </h4>
        <br/>
                         <h4>Changes (12)</h4>
                                 
    
<div id="page-diffs">
            <table class="diff" cellpadding="0" cellspacing="0">
            <tr><td class="diff-unchanged" >h1. Documentation <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The documentation is <span
class="diff-changed-words">split<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">ted</span></span>
into different parts: <br></td></tr>
            <tr><td class="diff-unchanged" > <br>   * [Getting Started],
the right place to start! <br>   * [The Sling Engine], all about the heart of Sling
<br>   * [Development], how do I get and develop with Sling <br></td></tr>
            <tr><td class="diff-changed-lines" >* [Bundles], which bundle <span
class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">brings</span>
<span class="diff-added-words"style="background-color: #dfd;">delivers</span>
which features to Sling <br></td></tr>
            <tr><td class="diff-unchanged" >   * [Tutorials &amp; How-Tos]
<br>   * [Wiki|http://cwiki.apache.org/SLING/] <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h2. How can you contribute <br>
<br></td></tr>
            <tr><td class="diff-changed-lines" >We&#39;re on the way to improve
the documentation, but it&#39;s a long way. If you <span class="diff-added-words"style="background-color:
#dfd;">would</span> like to contribute to the documentation you are very welcome.
Please directly post your proposals to the [public wiki|http://cwiki.apache.org/SLING/] or
post your suggestions to the mailing list. <br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h4. Main Site <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The main Sling Site is maintained
in the Confluence Wiki Space _SLINGxSITE_. The <span class="diff-changed-words">content<span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">s</span></span>
of this space is automatically synchronized with the web server with a simple shell script
[^sling.sh] which is called regularly as per the following {{crontab}} entry: <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h4. Secondary Site <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >The Sling site contains secondary
site parts <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">which</span>
<span class="diff-added-words"style="background-color: #dfd;">that</span> are
maintained in the Apache SVN repository at [http://svn.apache.org/repos/asf/sling/site]. Updates
to secondary parts of the site have to be done in the following steps: <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >1. Checkout or update the [site|https://svn.apache.org/repos/asf/sling/site]
tree form <span class="diff-changed-words">SVN<span class="diff-added-chars"style="background-color:
#dfd;">.</span></span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >2. Apply your <span class="diff-changed-words">changes<span
class="diff-added-chars"style="background-color: #dfd;">.</span></span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br></td></tr>
            <tr><td class="diff-changed-lines" >3. Commit the changes back into
<span class="diff-changed-words">SVN<span class="diff-added-chars"style="background-color:
#dfd;">.</span></span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >5. <span class="diff-changed-words">Go<span
class="diff-added-chars"style="background-color: #dfd;"> </span>to</span> the
location from where infrastructure mirroring is getting the actual sites and update from <span
class="diff-changed-words">SVN<span class="diff-added-chars"style="background-color:
#dfd;">.</span></span> <br></td></tr>
            <tr><td class="diff-unchanged" > <br>{code} <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >{code} <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >I am still <span class="diff-changed-words">unsure<span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">,</span></span>
whether it makes sense to generate aggregate JavaDoc for all (or part of) the bundles of Sling.
See also below regarding the Sites. <br></td></tr>
            <tr><td class="diff-unchanged" > <br> <br>h3. The Bundle
Documentation <br> <br></td></tr>
            <tr><td class="diff-changed-lines" >Apart from the documentation of
Sling on the Site and in the Wiki, it would also be <span class="diff-changed-words">thinkable<span
class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">,</span></span>
that we accompany the source modules with some documentation and generate this using the Maven
Site plugin. My tests so far <span class="diff-added-words"style="background-color: #dfd;">for</span>
generating a multi-module site <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">has</span>
<span class="diff-added-words"style="background-color: #dfd;">have</span> not
been very <span class="diff-changed-words">successful<span class="diff-deleted-chars"style="color:#999;background-color:#fdd;text-decoration:line-through;">l</span>.</span>
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. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>To prepare such Bundle
Documentation I added a first shot at site generation setup to the parent project. For now,
this includes the module&#39;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: <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >|| Property || Description || <br>|
{{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). | <br></td></tr>
            <tr><td class="diff-changed-lines" >| {{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 <span class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">exlucsion,</span>
<span class="diff-added-words"style="background-color: #dfd;">exclusion,</span>
list them in the format suitable for the [{{excludePackageNames}}|http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#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}}. | <br></td></tr>
        </table>
</div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="Documentation-Documentation"></a>Documentation</h1>

<p>The documentation is split into different parts:</p>

<ul>
	<li><a href="/confluence/display/SLINGxSITE/Getting+Started" title="Getting Started">Getting
Started</a>, the right place to start!</li>
	<li><a href="/confluence/display/SLINGxSITE/The+Sling+Engine" title="The Sling Engine">The
Sling Engine</a>, all about the heart of Sling</li>
	<li><a href="/confluence/display/SLINGxSITE/Development" title="Development">Development</a>,
how do I get and develop with Sling</li>
	<li><a href="/confluence/display/SLINGxSITE/Bundles" title="Bundles">Bundles</a>,
which bundle delivers which features to Sling</li>
	<li><a href="/confluence/pages/viewpage.action?pageId=119113" title="Tutorials &amp;
How-Tos">Tutorials &amp; How&#45;Tos</a></li>
	<li><a href="http://cwiki.apache.org/SLING/" class="external-link" rel="nofollow">Wiki</a></li>
	<li><a href="/confluence/display/SLINGxSITE/Configuration" title="Configuration">Configuration</a></li>
	<li><a href="http://sling.apache.org/apidocs/sling5/index.html" class="external-link"
rel="nofollow">API Doc</a></li>
</ul>



<h2><a name="Documentation-Howcanyoucontribute"></a>How can you contribute</h2>

<p>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 <a href="http://cwiki.apache.org/SLING/" class="external-link" rel="nofollow">public
wiki</a> or post your suggestions to the mailing list.</p>


<h2><a name="Documentation-Howisthedocumentationgenerated"></a>How is the
documentation generated</h2>

<p>The basic documentation of Sling is made up of four parts:</p>

<ol>
	<li>The Sling Site at <a href="http://sling.apache.org/" class="external-link" rel="nofollow">http://sling.apache.org/</a>
(you are here)</li>
	<li>The Public Wiki at <a href="http://cwiki.apache.org/SLING" class="external-link"
rel="nofollow">http://cwiki.apache.org/SLING</a></li>
	<li>The JavaDoc</li>
	<li>The Bundle documentation</li>
</ol>


<p>This page is about how this documentation is maintained and who is allowed to do
what.</p>


<h3><a name="Documentation-TheSlingSite"></a>The Sling Site</h3>

<h4><a name="Documentation-MainSite"></a>Main Site</h4>

<p>The main Sling Site is maintained in the Confluence Wiki Space <em>SLINGxSITE</em>.
The content of this space is automatically synchronized with the web server with a simple
shell script <a href="/confluence/download/attachments/76154/sling.sh?version=1&amp;modificationDate=1268494867000">sling.sh</a>
which is called regularly as per the following <tt>crontab</tt> entry:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
# sync wiki autoexport to Sling site
1 * * * * (/home/fmeschbe/sling.sh)
</pre>
</div></div>

<p>Thus, after editing the site source in the Wiki, the rest happens automatically,
it just takes some time &#8211; in the order 2 hours or so &#8211; before the changes
are visible at <a href="http://sling.apache.org/" class="external-link" rel="nofollow">http://sling.apache.org/</a>.</p>

<p>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.</p>

<p>The main site is located in the <tt>site</tt> folder below the Site URL
<a href="http://sling.apache.org/" class="external-link" rel="nofollow">http://sling.apache.org/</a>
to which users are redirected automatically.</p>

<h4><a name="Documentation-SecondarySite"></a>Secondary Site</h4>

<p>The Sling site contains secondary site parts that are maintained in the Apache SVN
repository at <a href="http://svn.apache.org/repos/asf/sling/site" class="external-link"
rel="nofollow">http://svn.apache.org/repos/asf/sling/site</a>. Updates to secondary
parts of the site have to be done in the following steps:</p>

<p>1. Checkout or update the <a href="https://svn.apache.org/repos/asf/sling/site"
class="external-link" rel="nofollow">site</a> tree form SVN.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
$ svn checkout https:<span class="code-comment">//svn.apache.org/repos/asf/sling/site</span>
</pre>
</div></div>

<p>2. Apply your changes.</p>

<p>3. Commit the changes back into SVN.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
$ svn commit -m<span class="code-quote">"&lt;enter your message here&gt;"</span>
</pre>
</div></div>

<p>4. Login to <tt>people.apache.org</tt></p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
$ ssh people.apache.org
</pre>
</div></div>

<p>5. Go to the location from where infrastructure mirroring is getting the actual sites
and update from SVN.</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
$ cd /x1/www/sling.apache.org
$ svn update
</pre>
</div></div>

<p>After some time, the updates will be synchronized to the web servers and can be accessed.</p>


<h3><a name="Documentation-ThePublicWiki"></a>The Public Wiki</h3>

<p>The public wiki of Sling is available at <a href="http://cwiki.apache.org/SLING"
class="external-link" rel="nofollow">http://cwiki.apache.org/SLING</a> and is maintained
in the Confluence space <em>SLING</em>. This is a public wiki, in that after self-registration,
everybody is allowed to edit content.</p>


<h3><a name="Documentation-TheJavaDoc"></a>The JavaDoc</h3>

<p>Up until now the JavaDoc of the Sling Bundles has not been published.</p>

<p>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 <a
href="http://people.apache.org/~fmeschbe/slingdocs.762729/" class="external-link" rel="nofollow">http://people.apache.org/~fmeschbe/slingdocs.762729/</a>.
This JavaDoc has been generated as follows:</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
$ svn export -r 762729 http:<span class="code-comment">//svn.apache.org/repos/asf/incubator/sling/trunk
sling
</span>$ mvn -DexcludePackageNames=<span class="code-quote">"*.impl:*.internal:*.jsp:sun.misc:*.juli"</span>
org.apache.maven.plugins:maven-javadoc-plugin:2.5:aggregate
</pre>
</div></div>

<p>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.</p>


<h3><a name="Documentation-TheBundleDocumentation"></a>The Bundle Documentation</h3>

<p>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.</p>

<p>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:</p>

<div class='table-wrap'>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> <tt>site.jira.version.id</tt> </td>
<td class='confluenceTd'> 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). </td>
</tr>
<tr>
<td class='confluenceTd'> <tt>site.javadoc.exclude</tt> </td>
<td class='confluenceTd'> The Java packages to not include with the JavaDoc generation.
By default all packages containing <tt>impl</tt> or <tt>internal</tt>
in their name are excluded. To add more packages for exclusion, list them in the format suitable
for the <a href="http://maven.apache.org/plugins/maven-javadoc-plugin/javadoc-mojo.html#excludePackageNames"
class="external-link" rel="nofollow"><tt>excludePackageNames</tt></a>
property of the Maven JavaDoc plugin. For example, to exclude any <tt>jsp</tt>
and <tt>juli</tt> packages (see the <em>scripting/jsp</em> bundle),
this property would be set to <tt>&#42;.jsp:&#42;.juli</tt>. </td>
</tr>
</tbody></table>
</div>

    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/Documentation">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=76154&revisedVersion=18&originalVersion=17">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/SLINGxSITE/Documentation?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message