[MSITE-1010] Add documentation how site deployment inheritance works

Co-authored-by: Michael Osipov <michaelo@apache.org> This closes #194
apache · Jul 20, 2024 · 3ff66a9 · 3ff66a9
1 parent 96b6971
commit 3ff66a9
Show file tree

Hide file tree

Showing 2 changed files with 81 additions and 3 deletions.
diff --git a/src/site/apt/examples/inheritance-site-distribution-management.apt b/src/site/apt/examples/inheritance-site-distribution-management.apt
@@ -0,0 +1,76 @@
+ ------
+ Inheritance of Site Distribution Management
+ ------
+Matthias Bünger
+ ------
+ 2024-07-07
+ ------
+
+ ~~ Licensed to the Apache Software Foundation (ASF) under one
+ ~~ or more contributor license agreements.  See the NOTICE file
+ ~~ distributed with this work for additional information
+ ~~ regarding copyright ownership.  The ASF licenses this file
+ ~~ to you under the Apache License, Version 2.0 (the
+ ~~ "License"); you may not use this file except in compliance
+ ~~ with the License.  You may obtain a copy of the License at
+ ~~
+ ~~   http://www.apache.org/licenses/LICENSE-2.0
+ ~~
+ ~~ Unless required by applicable law or agreed to in writing,
+ ~~ software distributed under the License is distributed on an
+ ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~~ KIND, either express or implied.  See the License for the
+ ~~ specific language governing permissions and limitations
+ ~~ under the License.
+
+ ~~ NOTE: For help with the syntax of this file, see:
+ ~~ http://maven.apache.org/doxia/references/apt-format.html
+
+
+Inheritance of the Site Distribution Management
+
+  Inside your POM you can not only configure the <<<distributionManagement>>> for the releases and snapshots
+  of your project, but also where to deploy your site when using the <<<{{{../deploy-mojo.html}site:deploy}}>>>
+  goal. The following configuration would deploy the project's site to a local directory called <<<bar>>>.
+
++-----+
+<distributionManagement>
+  <site>
+      <id>local</id>
+      <url>file:///C:/foo/bar</url>
+  </site>
+</distributionManagement>
++-----+
+
+  The content of this directory would look similar to the following after your deployment:
+
+-----
+bar/ (root of site)
+├── css
+└── report.html
+-----
+
+  You see that all files are placed directly inside the directory and that no subdirectory named after the <<<artifactId>>> is created.
+  That's a small, but important difference in comparison how the regular <<<deploy>>> phase of the build lifecycle works
+  where always a subdirectory is created for each project. So you have to be aware not to use the exact same value
+  for the site for multiple projects, as otherwise files of the first deployed project will be overwritten by the files
+  of the second deployed one and so on.
+
+  To handle this easily you can use a the same parent POM with each of your projects.
+  When using a parent POM with a project, the site configuration is inherited from the parent, but each child project
+  is located in a subdirectory with its <<<artifactId>>> name, resulting in a structure like in the following example:
+
+-----
+bar/ (root of site)
+├── css
+├── project-A
+│   ├── css
+│   └── report.html
+├── project-B
+│   ├── css
+│   └── report.html
+└── report.html
+-----
+
+  As you can see the site content of the parent POM is located in the root of the site directory, while the content of
+  each project using the parent POM (called "project-A" and "project-B" in the example) is located inside a subdirectory.
diff --git a/src/site/site.xml b/src/site/site.xml
@@ -19,9 +19,9 @@ specific language governing permissions and limitations
 under the License.
 -->
 
-<project xmlns="http://maven.apache.org/DECORATION/1.6.0"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://maven.apache.org/DECORATION/1.6.0 http://maven.apache.org/xsd/decoration-1.6.0.xsd">
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns="http://maven.apache.org/DECORATION/1.6.0"
+  xsi:schemaLocation="http://maven.apache.org/DECORATION/1.6.0 http://maven.apache.org/xsd/decoration-1.6.0.xsd">
   <body>
     <menu name="Overview">
       <item name="Introduction" href="index.html"/>
@@ -41,6 +41,8 @@ under the License.
       <item name="Building a multi-module site" href="/examples/multimodule.html"/>
       <item name="Configuring Site Run" href="/examples/siterun.html"/>
       <item name="Excluding Document Formats" href="/examples/moduleexcludes.html"/>
+      <item name="Inheritance of the Site Distribution Management"
+        href="/examples/inheritance-site-distribution-management.html"/>
     </menu>
 
     <menu name="Reports">