CAPI-SNAP-Doc/template/sec_template_structure.xml

<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
      <literal>Docs-Master</literal> and <literal>Docs-Template</literal>, both existing OpenPOWER Foundation GitHub projects 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 get the green directories and files by cloning <literal>Docs-Master</literal>, blue 
      directories and files by cloning <literal>Docs-Template</literal>, and the red files by cloning a hypothetical project
      <literal>my_project</literal>.</para>
      
      <para>Among these directories, 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" 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 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/template</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 depected 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>