CAPI-SNAP-Doc/doc_dev_guide/sec_template_structure.xml

<!--
  Copyright (c) 2016 OpenPOWER Foundation
  
  Licensed 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.
  
-->
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure">

     <title xml:id="section_template_structure_title">Understanding the project structure</title>
      <para>The OpenPOWER Foundation documentation build process involves dependency on a common
      framework and shared files.  As such, a deeper explanation about the relationships of key projects and their
      components may be helpful to prevent and diagnose documentation build problems. This section 
      provides a pictorial layout of key files and explains their roles and relationships.</para>

      <para>As mentioned multiple times throughout this guide, successful build of any OpenPOWER Foundation
      document requires two things:</para>
      <orderedlist>
	    <listitem><para>The cloning of the <literal>Docs-Master</literal> project.</para></listitem>
	    <listitem><para>The cloning of the specific documentation project into the same parent directory as the
	    <literal>Docs-Master</literal> project.</para></listitem>
      </orderedlist>     
      <para>To begin to understand why, let us use a picture.  The following graphic illustrates 
      the directory structure of three projects: two existing OpenPOWER Foundation GitHub projects,
      <literal>Docs-Master</literal> and <literal>Docs-Template</literal>, and a 
      hypothetical new project named <literal>my_project</literal>.</para>
      
      <figure pgwide="1" xml:id="project_structure_label">
        <title>Directory structure and key files in the OpenPOWER Foundation Docbook projects</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/project_structure_graphic.svg" format="SVG" scalefit="1" width="100%" />
          </imageobject>
        </mediaobject>
      </figure> 
      
      <para>To create this structure, one would clone the <literal>Docs-Master</literal> project to 
      get the <literal>Docs-Master</literal> directory and all its contents (shown above in green), 
      clone the <literal>Docs-Template</literal> project to get the <literal>Docs-Template</literal> directory
      and all its contents (shown in blue), and clone <literal>my_project</literal> project to get the
      <literal>my_project</literal> directory and all its contents (shown in red).</para>
      
      <para>Among these projects, the most important directory and project is <literal>Docs-Master</literal>.  Without this project
      and associated directory, no document will build. As depicted in the above figure, the <literal>Docs-Master</literal> directory
      must sit at a level equal to all other project directories.  Details on how to install this project can be found in the 
      <xref linkend="section_cloning_master_doc"/> section.</para>
      
      <para>Inside the <literal>Docs-Master</literal>project directory, the two most important pieces are a 
      <literal>commmon</literal> directory
      and a <literal>pom.xml</literal> file.  The directory contains common files used by all projects such as the common preface 
      (<literal>ch_preface.xml</literal>) and the common appendix (<literal>app_foundation.xml</literal>). The <literal>pom.xml</literal> file
      in this directory serves as the "Master POM" (POM stands for Program Object Model and serves as the main configuration file) 
      for all builds. This file references the OpenPOWER Maven Plugin JAR 
      (found in the OpenPOWER Foundation Repository at 
      <link xlink:href="http://openpowerfoundation.org/repo.openpowerfoundation.org/">http://openpowerfoundation.org/repo.openpowerfoundation.org/</link>)
      used to control the OpenPOWER 
      Foundation document builds where all other dependencies, supporting tools, and document build rules are defined. </para>

      <para>The <literal>Docs-Template</literal> project and directory are depicted in blue in the above figure.  The top level of the 
      project <literal>Docs-Template</literal> must be cloned into the same parent directory as the <literal>Docs-Master</literal>
      for Maven builds to complete successfully.
      At the top level of the <literal>Docs-Template</literal> project
      are a <literal>pom.xml</literal> referred to as the "Workgroup POM" and a single document directory (<literal>template</literal>).
      The "Workgroup POM" is a minimal POM file that locates the parent, "Master POM" in the <literal>Docs-Master</literal>project directory
      with a <literal>&lt;relativePath></literal> definition of <literal>../Docs-Master/pom.xml</literal>.
      The document directory contains the unique files used to create the document.  The two most important files in the 
      <literal>Docs-Template/doc_dev_guide</literal> directory (and in any project) are the <literal>pom.xml</literal> or "Document POM" which describes
      how to build the document and which points to the main document file, the <literal>bk_main.xml</literal> file.  This book file
      contains all the Docbook source, directly or through include statements (<literal>&lt;xi:include href="..."</literal>), 
      to build the document.</para>
      
      <para>For completeness of understanding, a hypothetical project <literal>my_project</literal> is also depicted in red.  Like all
      OpenPOWER Foundation projects, it is cloned at the correct level, equal to <literal>Docs-Master</literal>.  Like the 
      <literal>Docs-Template</literal> project, it has a "Workgroup POM" which will differ only in the <literal>&lt;modules></literal>
      section where it will describe two document projects, <literal>my_doc_1</literal> and <literal>my_doc_2</literal>.  But, each
      document directory has similar contents to <literal>Docs-Template/template</literal> -- a "Document POM" (<literal>pom.xml</literal>) 
      and a "Main book file" (<literal>bk_main.xml</literal>).</para>
</section>