Author: olamy
Date: Wed Jan 2 11:11:33 2013
New Revision: 1427742
URL: http://svn.apache.org/viewvc?rev=1427742&view=rev
Log:
add doc on site publish
Added:
archiva/site/src/site/apt/developers/publishing-site.apt (with props)
Added: archiva/site/src/site/apt/developers/publishing-site.apt
URL:
http://svn.apache.org/viewvc/archiva/site/src/site/apt/developers/publishing-site.apt?rev=1427742&view=auto
==============================================================================
--- archiva/site/src/site/apt/developers/publishing-site.apt (added)
+++ archiva/site/src/site/apt/developers/publishing-site.apt Wed Jan 2
11:11:33 2013
@@ -0,0 +1,117 @@
+ ------
+ Archiva Sites Publishing
+ ------
+
+Publishing the Archiva Site
+
+ The Archiva site, documentation and reference documentation are now
+ published to <<<http://archiva.apache.org/>>> using the
+ {{{http://www.apache.org/dev/project-site.html#svnpubsub} ASF's svnpubsub}}
+ service.
+
+ The files published to the site are all stored under the Subversion
+ repository at {{http://svn.apache.org/repos/asf/archiva/site-content/}}.
+
+ 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
+ {{{http://maven.apache.org/plugins/maven-scm-publish-plugin/}Maven SCM
Publish Plugin}}
+ for
+
{{{http://maven.apache.org/plugins/maven-scm-publish-plugin/examples/one-module-configuration.html}
+ Single module projects}} and
+
{{{http://maven.apache.org/plugins/maven-scm-publish-plugin/examples/multi-module-configuration.html}
+ 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 {{http://archiva.apache.org}} (where
+ you are reading this) has its source code in Subversion at
+ {{https://svn.apache.org/repos/asf/archiva/site}}.
+
+ 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 Archiva}}, 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 Archiva Documentation
+
+ The documentation displayed under the subdirectories of
+ {{http://archiva.apache.org/docs/}} has its source code in Subversion at
+ {{https://svn.apache.org/repos/asf/archiva/trunk/archiva-docs}}, 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 {{{./releasing.html} Releasing Archiva}} 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,
+ <<<http://svn.apache.org/repos/asf/archiva/site-content/docs/1.4-M4>>>.
+
+ For <<<site:stage>>> to apply correctly without needing a full checkout, a
+ 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. This
+ 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 {{http://archiva.apache.org/ref}}. 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
+ Archiva developers or users.
+
+ To publish the latest reference documents, you need to run:
+
+----
+cd archiva-modules
+mvn site site:stage scm-publish:publish-scm
+or
+sh ./deploySite.sh
+----
+
+ This will likely cause a very large commit, and should be done
+ infrequently. Once per release is likely to be adequate.
+
Propchange: archiva/site/src/site/apt/developers/publishing-site.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: archiva/site/src/site/apt/developers/publishing-site.apt
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
