You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

Error formatting macro: contentbylabel: com.atlassian.confluence.api.service.exceptions.BadRequestException: Could not parse cql : null

This document describes our site setup: what is where and how does it work.

Overview

Our website and documentation are kept in Confluence.

Since the confluence instance at https://cwiki.apache.org/confluence/ isn't capable of handling a lot of incoming requests, all spaces are statically exported.

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 /www/confluence-exports on people.apache.org.

On people.apache.org another cron job copies the exported Tapestry space to ~uli/public_html/tapestry-site/ which is available as http://people.apache.org/~uli/tapestry-site/.

This will shortly be updated to copy our space to a /www/tapestry.apache.org which is the folder that itself is copied out and available as http://tapestry.apache.org.

Yes, this is a bit Rube Goldberg, 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).

Content copied to /www/tapestry.apache.org 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 ~uli is available in real time.

Wiki Formatting Guidelines

  • Precede annotation names with '@'. If the annotation name is hyperlinked, put the '@' character outside of the link: @[AnnotationType|http://...AnnotationType.html]

  • The first reference to a type on a page should be a link to http://tapestry.apache.org/current/apidocs/... (or the component reference)
  • Treat the page title as if it were an h0. element, and put top level sections within the page as h1.
  • Page names as headings should have All Words Captialized.
  • For other headings, only the first word of multi-word headings should be capitalized, e.g. "h2. Naming conventions" (following Wikipedia)
  • Use code font for method and property names: myProperty, someMethod().
  • Use the default font for Class names (qualified or not).
  • Use the default font for path names.
  • Use {code} for listings, not {noformat}.
  • Use {noformat} for console output.
  • Images and diagrams should be small-sized thumbnails, centered, with no border.
  • 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.

  • 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 Component Templates

  • Proposed: User Guide pages should generally start with a right-floated "Related Articles" box that provides links to related content in the FAQ, Cookbook, Cheat Sheets, etc. Example
  • Proposed: The lead paragraph should generally lead with the title word or phrase in bold (following Wikipedia)

Website structure

The Index page includes the Banner and Key Features 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 Navigation, Small Banner and Footer pages exist.

Our Autoexport template glues everything together. It adds the contents of the Navigation and Footer pages in the appropriate places and on all pages except the Index page. It also adds the contents of the Small Banner page as well as the breadcrumbs navigation.

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.

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?

Updating the template

You must be a Confluence Administrator.

Unfortunately, Confluence can't read content directly from Subversion.

Checkout a workspace to https://svn.apache.org/repos/asf/tapestry/tapestry-site/branches/post-5.2-site

Edit the autoexport_template.txt there, then check it back in.

From the Browse menu (at the top of the Confluence page), select Confluence Admin.

From the Configuration left side menu, click Auto Export.

From AutoExport Templates Management you can scroll down to Apache Tapestry and click Edit Template.

Copy the contents of the autoexport_template.txt file to the text area and hit update.

Now, under Rebuild exported spaces, select Apache Tapestry and click Export Space(s).

  • No labels