continuum-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1427709 - in /continuum/site/src/site: apt/development/publishing-site.apt site.xml
Date Wed, 02 Jan 2013 08:53:54 GMT
Author: brett
Date: Wed Jan  2 08:53:53 2013
New Revision: 1427709

add instructions for publishing the sites and other documentation


Added: continuum/site/src/site/apt/development/publishing-site.apt
--- continuum/site/src/site/apt/development/publishing-site.apt (added)
+++ continuum/site/src/site/apt/development/publishing-site.apt Wed Jan  2 08:53:53 2013
@@ -0,0 +1,114 @@
+ ------
+ Continuum Site Publishing
+ ------
+Publishing the Continuum Site
+  The Continuum site, documentation and reference documentation are now
+  published to <<<>>> using the
+  {{{} ASF's svnpubsub}}
+  service.
+  The files published to the site are all stored under the Subversion
+  repository at {{}}.
+  This mostly operates like a normal site deployment, though there are some
+  specific customisations and special instructions for the reference library.
+  The processes follow those described for the
+  {{{}Maven SCM Publish Plugin}}
+  for
+  {{{}
+  Single module projects}} and
+  {{{}
+  Multi-module projects}} as applicable.
+  Each site checks out the production site data into the <<<site-publish>>>
+  directory of the current project, to avoid being cleaned as part of the
+  build. It is ignored by <<<svn>>> operations, but you should ensure that
+  the checkout is clean if you ever cancel or have a failure during a publish
+  operation. You can check it is clean by ensuring there is no data from
+  <<<svn status>>> in that directory, or by removing it and having it get
+  checked out again.
+* Editing and Publishing the Main Site
+  The site displayed at the root of {{}} (where
+  you are reading this) has its source code in Subversion at
+  {{}}.
+  To edit and publish the site, do the following:
+    [[1]] Checkout the source code from Subversion (if you follow the
+          instructions in {{{./building.html} Building Continuum}}, you will 
+          already have it.
+    [[2]] Make edits and check them using <<<mvn site>>> or <<<mvn
+          site:run>>> until satisfied.
+    [[3]] Commit your changes (making sure your working copy is completely up
+          to date first)
+    [[4]] Publish the site:
+mvn site-deploy
+  This site deployment can be done at any time, and is not tied to releases.
+  Note that since the main site also contains the (large!) <<<docs>>> and

+  <<<ref>>> directories in the <<<site-publish>>> directory,
there is a
+  special <<<setup-checkout>>> profile in place to get the initial checkout
+  without those directories. This will normally be activated whenever the
+  <<<site-publish>>> directory is missing - if you happen to have active
+  profiles from your <<<settings.xml>>> you may need to enable it explicitly
+  whenever you do a deployment and that checkout is missing: <<<mvn
+  site-deploy -Psetup-checkout>>>   
+* Editing and Publishing the Continuum Documentation
+  The documentation displayed under the subdirectories of
+  {{}} has its source code in Subversion at
+  {{}}, which
+  is part of the main project checkout.
+  The instructions for managing the documentation is the same as for the main
+  site, being published from the directory using:
+mvn site-deploy
+  However, in this case it is typically done as part of a release process - 
+  see {{{./release.html} Releasing Continuum}} for instructions on doing this.
+  The documentation remains versioned based on the release it is related to.
+  To best manage this with svnpubsub, the site is always published into a
+  directory <<<docs/latest>>>, only requiring a small number of modifications
+  to be made. Then, as part of the release instructions, the <<<latest>>>
+  directory is copied to the versioned location - for example,
+  <<<>>>.
+  For <<<site:stage>>> to apply correctly without needing a full checkout,
+  workaround is applied by setting the <<<distributionManagement/site/url>>>
+  element to match that of the parent site. The value is then overridden with
+  the correct value in the <<<maven-scm-publish-plugin>>> configuration.
+  avoids the Site plugin attempting to relativize links incorrectly.
+* Editing and Publishing the Reference Documentation
+  The reference documentation, including JavaDocs and source cross-reference,
+  is displayed under the URL {{}}. At this
+  time, only the latest reference documents are retained. They require quite
+  a lot of space, and historical information is of less relevance to
+  Continuum developers or users.
+  To publish the latest reference documents, you need to run:
+mvn site site:stage scm-publish:publish-scm
+  This will likely cause a very large commit, and should be done
+  infrequently. Once per release is likely to be adequate.

Modified: continuum/site/src/site/site.xml
--- continuum/site/src/site/site.xml (original)
+++ continuum/site/src/site/site.xml Wed Jan  2 08:53:53 2013
@@ -56,6 +56,7 @@
       <item name="Debugging Continuum" href="development/debugging.html"/>
       <item name="Development Convention" href="development/guide-continuum-development.html"/>
       <item name="Release Procedure" href="development/release.html"/>
+      <item name="Publishing the Site" href="development/publishing-site.html"/>
       <item name="Reference Library" href="/ref/latest"/>

View raw message