trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gunnar Tapper <tapper.gun...@gmail.com>
Subject Documentation Organization and Build
Date Sun, 20 Dec 2015 06:51:31 GMT
Hi,

Sorry, this became a long e-mail... In summary, I like input on:

1. docs/target/docs organization
2. move $SQ_HOME/pom.xml to docs/pom.xml
3. A single pom.xml for web site and all documents (with possible exception
of DCS and REST) vs. separate pom.xml files per manual and web site.
4. Centralize all documentation to docs
5. Create a docs/make file (only needed for separate pom.xml files -- the
current model)

In essence, I am trying to understand what the preferred strategy for the
web site and manuals is?

CURRENT SITUATION

1. The main pom.xml file builds the web-site files.
2. The main pom.xml file attempts to build some unknown manual but fails.
3. DCS and REST manuals are built from dcs/pom.xml and core/rest/pom.xml,
respectively.

I followed the DCS and REST examples for the Client Installation Guide for
now. But, I'm not sure what the strategy should be...

The website and all manuals BUT DCS and REST are located under the docs
directory, which is organized as follows:


   - docs/client_install: Client Install Guide
   - docs/command_interface: Command Interface Guide (needs to be ported to
   asciidoc)
   - docs/css: new directory, centralized style-sheet definition for all
   manuals in the docs directory; does not cover DCS and REST.
   - docs/odb_manual: odb Guide (needs to be ported to asciidoc)
   - docs/sql_reference: SQL Reference Guide (needs to be ported to
   asciidoc)
   - docs/src: web-site source
   - docs/target: web-site output, populated by building src from main
   pom.xml

docs/client_install/pom.xml now contains instructions to move the generated
.pdf and web-book files to docs/target/docs as follows:


   - target/docs/Trafodion_Client_Installation_Guide.pdf: well-known
   location for the latest version of the .pdf file. (Allows pages and manuals
   to reference to a well-known place that is version independent.)
   - target/docs/client_install: well-known location for web book
   - target/docs/<version>/Trafodion_Client_Installation_Guide.pdf:
   version-specific .pdf rendering
   - target/docs/<version</client_install/: version-specific web-book
   rendering.

I'm not sure if this is the best organization...

PROPOSED MODIFICATIONS

I think this is a cleaner way to organize the manuals:

   - target/docs/<manual-directory>: well-known location for both .pdf and
   web-book renderings
   - target/docs/<version>/<manual-directory>: version-specific location
   for .pdf and web-book renderings

In this model, we'd have:

   - target/docs/client_install
   - target/docs/command_interface
   - target/docs/dcs
   - target/docs/odb
   - target/docs/rest
   - target/docs/sql_reference
   - target/docs/1.3.0/client_install
   - target/docs/1.3.0/command_interface
   - target/docs/1.3.0/dcs
   - target/docs/1.3.0/odb
   - target/docs/1.3.0/rest
   - target/docs/1.3.0/sql_reference

A 1.5 update would overwrite:

   - target/docs/client_install
   - target/docs/command_interface
   - target/docs/dcs
   - target/docs/odb
   - target/docs/rest
   - target/docs/sql_reference

And create:

   - target/docs/1.5.0/client_install
   - target/docs/1.5.0/command_interface
   - target/docs/1.5.0/dcs
   - target/docs/1.5.0/odb
   - target/docs/1.5.0/rest
   - target/docs/1.5.0/sql_reference

On the web site, this translates to a docs directory with content as above.
A 1.5 checkin would therefore:

   - Overwrite the well-known location documents
   - Keep the 1.3.0 documents
   - Add the 1.5.0 documents

Is this an OK strategy for the organization of manuals?

MOVING FILES

How should the web-site and documents be built? A single main pom.xml file
or a per-document pom.xml file? Looking at the main make file, it doesn't
seem to build the web-site or the documentation so there should be some
freedom, right? (DCS and REST are build by their respective make files.

I find the location of the web-site pom.xml file weird. Shouldn't it be in
the docs directory since that's what it builds? If so, then it might make
sense to create a docs/make file that can run make for the web site as well
as the different manuals. Is there a required for a pom.xml under the root
source directory?

I get why the DCS and REST manuals are located where they are but it seems
that manuals are scattered around but do they need to be, especially given
that we should have a common stylesheet for all manuals? Also, it's not
possible to build the DCS and REST manuals standalone; they pull in a lot
of stuff required to build the actual component.

Would it be better to have all manuals and the web site under the docs
directory as follows:


   - make: make file for web site and manuals, invokes per-manual pom.xml
   files and web-site pom.xml file
   - pom.xml: maven pom for web site only
   - docs/client_install: Client Install Guide
   - docs/command_interface: Command Interface Guide
   - docs/css: centralized style-sheet definition for all manuals
   - docs/dcs: DCS Guide
   - docs/odb: odb Guide
   - docs/sql_reference: SQL Reference Guide
   - docs/rest: REST Guide
   - docs/src: web-site source
   - docs/target: web-site output

This would be the cleanest approach since everything is in one place. Would
this be OK or do we need to keep DCS and REST where they are? If so, we can
still use a central stylesheet and move the generated files to the right
place; it's just a little uglier but no big deal.

That's all. Now, go back to the beginning of the e-mail for a summary of
the decisions I'm asking for. :)

-- 
Thanks,

Gunnar
*If you think you can you can, if you think you can't you're right.*

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message