src/site/apt/developers/publishing-site.apt

 ------
 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
  <<<git 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 Git at
  {{https://gitbox.apache.org/repos/asf/archiva-site.git}}.

  To edit and publish the site, do the following:

    [[1]] Checkout the source code from Git (if you follow the
          instructions in {{{./building.html} Building Archiva}}, you know
          how to 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 Git at
  {{https://gitbox.apache.org/repos/asf/archiva.git}} directory 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.

* Publishing Redback site

  The redback is stored under the Subversion repository at {{https://svn.apache.org/repos/asf/archiva/redback/redback-site/trunk}}.

  It's displayed under the URL {{http://archiva.apache.org/redback}}.

  To publish documentation, you need to run:

----
mvn site-deploy
----

* Publishing Redback Core reference

  The Redback core reference is displayed under the URL {{http://archiva.apache.org/redback/core}}.

  It contains javadoc for Redback core.

  To publish documentation, you need to run:

----
mvn clean site-deploy scm-publish:publish-scm
or
sh ./deploySite.sh
----

* Publishing Redback Components reference

  The Redback components reference is displayed under the URL {{http://archiva.apache.org/redback/components}}.

  It contains javadoc for Redback components.

  To publish documentation, you need to run:

----
mvn clean site-deploy scm-publish:publish-scm
or
sh ./deploySite.sh
----