tapestry-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r880797 - in /websites/production/tapestry/content: cache/main.pageCache confluence-site-setup.html
Date Wed, 02 Oct 2013 02:20:40 GMT
Author: buildbot
Date: Wed Oct  2 02:20:40 2013
New Revision: 880797

Log:
Production update by buildbot for tapestry

Modified:
    websites/production/tapestry/content/cache/main.pageCache
    websites/production/tapestry/content/confluence-site-setup.html

Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.

Modified: websites/production/tapestry/content/confluence-site-setup.html
==============================================================================
--- websites/production/tapestry/content/confluence-site-setup.html (original)
+++ websites/production/tapestry/content/confluence-site-setup.html Wed Oct  2 02:20:40 2013
@@ -69,10 +69,6 @@
 <div id="content">
 <div id="ConfluenceContent"><div class="navmenu" style="float:right; background:#eee;
margin:3px; padding:3px"><table class="tableview" width="100%"><tr><th colspan="1"
rowspan="1" style="padding: 3px 3px 3px 0px">Related Articles</th></tr><tr><td
colspan="1" rowspan="1">
                                  <span class="icon icon-page" title="Page">Page:</span>
-                         <a shape="rect" href="confluence-site-setup.html">Confluence
Site Setup</a>
-        
-                                            </td></tr><tr><td colspan="1"
rowspan="1">
-                                 <span class="icon icon-page" title="Page">Page:</span>
                          <a shape="rect" href="developer-information.html">Developer
Information</a>
         
                                             </td></tr><tr><td colspan="1"
rowspan="1">
@@ -91,62 +87,75 @@
                                  <span class="icon icon-page" title="Page">Page:</span>
                          <a shape="rect" href="building-tapestry-from-source.html">Building
Tapestry from Source</a>
         
+                                            </td></tr><tr><td colspan="1"
rowspan="1">
+                                 <span class="icon icon-page" title="Page">Page:</span>
+                         <a shape="rect" href="confluence-site-setup.html">Confluence
Site Setup</a>
+        
                                             </td></tr></table>
 </div> 
 
-<p>This document describes our site setup: what is where and how does it work.</p>
+<p>This document describes our web site setup: what is where and how it works.</p>
 
 <h1><a shape="rect" name="ConfluenceSiteSetup-Overview"></a>Overview</h1>
 
-<p>Our website and documentation are kept in Confluence. </p>
+<p>Most of the web site and documentation (with the notable exception of the Javadoc
API pages) are kept in Confluence.</p>
 
-<p>Since the confluence instance at <a shape="rect" class="external-link" href="https://cwiki.apache.org/confluence/">https://cwiki.apache.org/confluence/</a>
isn't capable of handling a lot of incoming requests, all spaces are statically exported.
</p>
+<p>Since the Confluence instance at <a shape="rect" class="external-link" href="https://cwiki.apache.org/confluence/">https://cwiki.apache.org/confluence/</a>
isn't capable of handling a lot of incoming requests, all wiki spaces are statically exported.
The SiteExporter program is responsible for that. Once a page in Confluence changes, that
page gets re-exported automatically.</p>
 
-<p>The Autoexport plugin for Confluence is responsible for that. Once a page in Confluence
changes, that page gets re-exported automatically. The Autoexport plugin is configured to
export the pages to a directory on thor (the machine Confluence is running on). From there
a cron job copies the exports to <tt>/www/confluence-exports</tt> on people.apache.org.
</p>
+<h2><a shape="rect" name="ConfluenceSiteSetup-HowSiteExporterworks"></a>How
SiteExporter works</h2>
 
-<p>On people.apache.org <em>another</em> cron job copies the exported Tapestry
space to <tt>~uli/public_html/tapestry-site/</tt> which is available as <a
shape="rect" class="external-link" href="http://people.apache.org/~uli/tapestry-site/">http://people.apache.org/~uli/tapestry-site/</a>.
</p>
+<p><em>For more details see the <a shape="rect" class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/README">SiteExporter
README</a>.</em></p>
 
-<div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1">This
will shortly be updated to copy our space to a <tt>/www/tapestry.apache.org</tt>
which is the folder that itself is copied out and available as <a shape="rect" class="external-link"
href="http://tapestry.apache.org">http://tapestry.apache.org</a>.</td></tr></table></div>
+<p>SiteExporter is a command-line Java program that is run hourly (currently at 20
minutes after the hour) from Apache's BuildBot. It makes a web service call to Confluence
(to its RSS feed, actually) to get a list of each page that has changed since the last run,
and the HTML-formatted export of those pages. For each, it post-processes the file (described
below). Finally, SiteExporter commits all changed HTML files into Tapestry's part of the Apache
Subversion repository, which (nearly instantly) makes it available to the public at <a
shape="rect" class="external-link" href="http://tapestry.apache.org">http://tapestry.apache.org</a>,
and commit emails are sent to Tapestry's "commits" mailing list.</p>
 
-<p>Yes, this is a bit <a shape="rect" class="external-link" href="http://en.wikipedia.org/wiki/Rube_Goldberg_machine"
>Rube Goldberg</a>, and the multiple steps, hops, and cron jobs mean it can be quite
some time between a change in Confluence, and the content being visible (possibly a couple
of hours).</p>
+<p>Attachments (to Confluence pages) are exported in roughly the same way.</p>
 
-<div class="panelMacro"><table class="infoMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/information.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1">Content
copied to <tt>/www/tapestry.apache.org</tt> is not immediately visible; yet another
cron job (!) copies this content to the main Apache web server, about once an hour. On the
other hand, content <tt>~uli</tt> is available in real time.</td></tr></table></div>
+<p>The time between saving a change in Confluence and seeing the result on the public
site is at most 1 hour, depending on when you do it. If you save a change at 19 minutes after
the hour you'll see the change in about a minute. If you publish it at 21 minutes after the
hour then you'll have to wait almost an hour.</p>
 
-<h1><a shape="rect" name="ConfluenceSiteSetup-WikiFormattingGuidelines"></a>Wiki
Formatting Guidelines</h1>
+<div class="table-wrap">
+<table class="confluenceTable"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"> HTML files in SVN </td><td colspan="1" rowspan="1" class="confluenceTd">
<a shape="rect" class="external-link" href="https://svn.apache.org/repos/infra/websites/production/tapestry">https://svn.apache.org/repos/infra/websites/production/tapestry</a>
</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> Cache
File </td><td colspan="1" rowspan="1" class="confluenceTd"> <a shape="rect"
class="external-link" href="https://svn.apache.org/repos/infra/websites/production/tapestry/content/cache/main.pageCache">https://svn.apache.org/repos/infra/websites/production/tapestry/content/cache/main.pageCache</a>
</td></tr><tr><td colspan="1" rowspan="1" class="confluenceTd"> SiteExporter
source </td><td colspan="1" rowspan="1" class="confluenceTd"> <a shape="rect"
class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk">https://svn.apache.org/repos/asf/tapestry/ta
 pestry-site/trunk</a> </td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"> Velocity template </td><td colspan="1" rowspan="1" class="confluenceTd">
<a shape="rect" class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/template/template.vm">https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/template/template.vm</a>
</td></tr></tbody></table>
+</div>
 
-<ul><li>Precede annotation names with '@'.  If the annotation name is hyperlinked,
put the '@' character <em>outside</em> of the link:  @[AnnotationType|http://...AnnotationType.html]</li><li>The
first reference to a type on a page should be a link to <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/">http://tapestry.apache.org/current/apidocs/</a>...
 (or the component reference)</li><li>Treat the page title as if it were an h0.
element, and put top level sections within the page as h1.</li><li>Page names
as headings should have All Words Captialized.</li><li>For other headings, only
the first word of multi-word headings should be capitalized, e.g. "h2. Naming conventions"
(following Wikipedia)</li><li>Use <tt>code</tt> font for method and
property names:  <tt>myProperty</tt>, <tt>someMethod()</tt>.</li><li>Use
the default font for Class names (qualified or not).</li><li>Use the default font
for path names.</li><li>Use {code} for listings, not 
 {noformat}.</li><li>Use {noformat} for console output.</li><li>Images
and diagrams should be small-sized thumbnails, centered, with no border.</li><li>Use
the <a shape="rect" href="since-and-deprecated-user-macros.html" title="Since and Deprecated
User Macros">Since and Deprecated</a> macros to mark new or deprecated features.</li><li><em>Proposed:
Each page should include explicit links to its child pages. Don't rely on the "Child Pages"
links at the bottom, which don't carry over to the exported site.</em></li><li><em>Proposed:
In pages other than the User Guide pages, subsections that briefly discuss topics that are
more fully covered in the User Guide should lead with a "Main Article: [Foo]" line, where
Foo is the name of the page in the User Guide. Example: the "Template Localization" section
of <a shape="rect" href="component-templates.html" title="Component Templates">Component
Templates</a></em></li><li><em>Proposed: User Guide pages should
generally start with a right-float
 ed "Related Articles" box that provides links to related content in the FAQ, Cookbook, Cheat
Sheets, etc.  <a shape="rect" href="component-classes.html" title="Component Classes">Example</a></em></li><li><em>Proposed:
The lead paragraph should generally lead with the title word or phrase in bold (following
Wikipedia)</em></li></ul>
 
+<h3><a shape="rect" name="ConfluenceSiteSetup-PostprocessingHTMLPages"></a>Post-processing
HTML Pages</h3>
 
-<h1><a shape="rect" name="ConfluenceSiteSetup-Websitestructure"></a>Website
structure</h1>
+<p>HTML pages exported from Confluence are post-processed in several ways before being
committed to SVN. Here are just a few of the things going on:</p>
 
-<p>The <a shape="rect" href="index.html" title="Index">Index</a> page includes
the <a shape="rect" href="banner.html" title="Banner">Banner</a> and <a shape="rect"
href="key-features.html" title="Key Features">Key Features</a> pages as well as the
blog posts. All other pages are just plain pages and may or may not include other parts. In
addition the <a shape="rect" href="navigation.html" title="Navigation">Navigation</a>,
<a shape="rect" href="small-banner.html" title="Small Banner">Small Banner</a>
and <a shape="rect" href="footer.html" title="Footer">Footer</a> pages exist.</p>
+<ul><li>Tagsoup is used to clean up the HTML.</li><li>The breadcrumb
links are updated.</li><li>Empty paragraph (&lt;p&gt;) tags are removed
from the top of the page.</li><li>{code} macro output (code examples) are detected,
and SyntaxHighlighter JavaScript links are added to the page when needed.</li><li>{include}
tags (when one Confluence page includes another) are detected, causing the <em>including</em>
page to be regenerated autoamtically.</li><li>{children} tags are also detected
and handled</li></ul>
 
-<p>Our <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/tapestry/tapestry-site/branches/post-5.2-site/autoexport_template.txt">Autoexport
template</a> glues everything together. It adds the contents of the <a shape="rect"
href="navigation.html" title="Navigation">Navigation</a> and <a shape="rect" href="footer.html"
title="Footer">Footer</a> pages in the appropriate places and on all pages except
the <a shape="rect" href="index.html" title="Index">Index</a> page.  It also adds
the contents of the <a shape="rect" href="small-banner.html" title="Small Banner">Small
Banner</a> page as well as the breadcrumbs navigation.</p>
 
-<p>Because we include some pages in others it is sometimes necessary to reexport the
whole space because the Autoexport plugin will only export the changed page, not the pages
where the changed page is included. To do so you have to be a confluence administrator. You
can then manually export our space via the Autoexport administrative console.</p>
+<h2><a shape="rect" name="ConfluenceSiteSetup-ManualIntervention"></a>Manual
Intervention</h2>
 
-<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1">HLS:
I've noticed that pages with footnotes that are combined with the {include} macro do not render
correctly ... the footnote numbers and anchors reset back to 1 for each included page. Perhaps
there's a way to fix that with the template?</td></tr></table></div>
+<p>You can cause the <em>whole site</em> to be republished by deleting
the main.pageCache file (above) in the subversion repo. This is usually only needed after
changing the template.</p>
 
-<h1><a shape="rect" name="ConfluenceSiteSetup-Updatingthetemplate"></a>Updating
the template</h1>
+<h2><a shape="rect" name="ConfluenceSiteSetup-ChangingSiteExporteritself"></a>Changing
SiteExporter itself</h2>
+
+<p>Currently the SiteExporter source code is an unmodified copy of a program of the
same name written by Dan Kulp for the Apache CXF project and also used by Camel, Geronimo,
and Struts (and possibly others). It can be customized, but proceed with caution, because
any customizations will make it harder to pull in future changes from the original CXF SiteExporter
code. The CXF SiteExporter is likely to change as Confluence versions change.</p>
 
-<p>You must be a Confluence Administrator.</p>
+<p>To pick up changes to the original CXF SiteExporter code, just compare <a shape="rect"
class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/trunk/src/main/java/org/apache/cxf/cwiki">the
Tapestry source code</a> with <a shape="rect" class="external-link" href="http://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/">the
CXF source code</a>.</p>
 
-<p>Unfortunately, Confluence can't read content directly from Subversion.</p>
+<hr>
 
-<p>Checkout a workspace to <a shape="rect" class="external-link" href="https://svn.apache.org/repos/asf/tapestry/tapestry-site/branches/post-5.2-site">https://svn.apache.org/repos/asf/tapestry/tapestry-site/branches/post-5.2-site</a></p>
+<h1><a shape="rect" name="ConfluenceSiteSetup-WikiFormattingGuidelines"></a>Wiki
Formatting Guidelines</h1>
 
-<p>Edit the autoexport_template.txt there, then check it back in.</p>
+<ul><li>Precede annotation names with '@'.  If the annotation name is hyperlinked,
put the '@' character <em>outside</em> of the link:  @[AnnotationType|http://...AnnotationType.html]</li><li>The
first reference to a type on a page should be a link to <a shape="rect" class="external-link"
href="http://tapestry.apache.org/current/apidocs/">http://tapestry.apache.org/current/apidocs/</a>...
 (or the component reference)</li><li>Treat the page title as if it were an h0.
element, and put top level sections within the page as h1.</li><li>Page names
as headings should have All Words Captialized.</li><li>For other headings, only
the first word of multi-word headings should be capitalized, e.g. "h2. Naming conventions"
(following Wikipedia)</li><li>Use <tt>code</tt> font for method and
property names:  <tt>myProperty</tt>, <tt>someMethod()</tt>.</li><li>Use
the default font for Class names (qualified or not).</li><li>Use the default font
for path names.</li><li>Use {code} for listings, not 
 {noformat}.</li><li>Use {noformat} for console output.</li><li>Images
and diagrams should be small-sized thumbnails, centered, with no border.</li><li>Use
the <a shape="rect" href="since-and-deprecated-user-macros.html" title="Since and Deprecated
User Macros">Since and Deprecated</a> macros to mark new or deprecated features.</li><li><em>Proposed:
Each page should include explicit links to its child pages. Don't rely on the "Child Pages"
links at the bottom, which don't carry over to the exported site.</em></li><li><em>Proposed:
In pages other than the User Guide pages, subsections that briefly discuss topics that are
more fully covered in the User Guide should lead with a "Main Article: [Foo]" line, where
Foo is the name of the page in the User Guide. Example: the "Template Localization" section
of <a shape="rect" href="component-templates.html" title="Component Templates">Component
Templates</a></em></li><li><em>Proposed: User Guide pages should
generally start with a right-float
 ed "Related Articles" box that provides links to related content in the FAQ, Cookbook, Cheat
Sheets, etc.  <a shape="rect" href="component-classes.html" title="Component Classes">Example</a></em></li><li><em>Proposed:
The lead paragraph should generally lead with the title word or phrase in bold (following
Wikipedia)</em></li></ul>
 
-<p>From the <b>Browse</b> menu (at the top of the Confluence page), select
<b>Confluence Admin</b>.</p>
 
-<p>From the <b>Configuration</b> left side menu, click <b>Auto Export</b>.</p>
+<h1><a shape="rect" name="ConfluenceSiteSetup-Websitestructure"></a>Website
structure</h1>
 
-<p>From <b>AutoExport Templates Management</b> you can scroll down to <b>Apache
Tapestry</b> and click <b>Edit Template</b>.</p>
+<p>The <a shape="rect" href="index.html" title="Index">Index</a> page includes
the <a shape="rect" href="banner.html" title="Banner">Banner</a> and <a shape="rect"
href="key-features.html" title="Key Features">Key Features</a> pages as well as the
blog posts. Most other pages are just plain pages and may or may not include other parts.
In addition the <a shape="rect" href="navigation.html" title="Navigation">Navigation</a>,
<a shape="rect" href="small-banner.html" title="Small Banner">Small Banner</a>
and <a shape="rect" href="footer.html" title="Footer">Footer</a> pages exist.</p>
+
+<p>Our SiteExporter template (described above) glues everything together. It adds the
contents of the <a shape="rect" href="navigation.html" title="Navigation">Navigation</a>
and <a shape="rect" href="footer.html" title="Footer">Footer</a> pages in the
appropriate places and on all pages except the <a shape="rect" href="index.html" title="Index">Index</a>
page.  It also adds the contents of the <a shape="rect" href="small-banner.html" title="Small
Banner">Small Banner</a> page as well as the breadcrumbs navigation.</p>
+
+<div class="panelMacro"><table class="warningMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/forbidden.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1">HLS:
I've noticed that pages with footnotes that are combined with the {include} macro do not render
correctly ... the footnote numbers and anchors reset back to 1 for each included page. Perhaps
there's a way to fix that with the template?</td></tr></table></div>
+
+<h1><a shape="rect" name="ConfluenceSiteSetup-Updatingthetemplate"></a>Updating
the template</h1>
 
-<p>Copy the contents of the autoexport_template.txt file to the text area and hit update.</p>
+<p>You must be a Tapestry committer or otherwise have write access to the subversion
repository (see link above).</p>
 
-<p>Now, under <b>Rebuild exported spaces</b>, select <b>Apache Tapestry</b>
and click <b>Export Space(s)</b>.</p>
+<p>To edit the template:</p>
 
+<ol><li>check out the SiteExporter source project (see link above)</li><li>find
and edit the template.vm file</li><li>commit your changes</li></ol>
 
 </div>
 </div>



Mime
View raw message