You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

Contains information about how to add and modify Trafodion documentation that is part of the Trafodion source tree. This documentation is written in asciidoc.

Source

Documents do not include version information as part of the file name.

Source Location

DocumentSource FormatSource TreeOutput Format
Client Installation Guideasciidoc
docs/client_install/
Web Book, PDF
Command Interface Guideasciidoc
docs/command_interface/
Web Book, PDF
Contributor Guideasciidoc
docs/contributor_guide/
Web Book, PDF
DCS Reference Guideasciidoc
dcs/src/main/asciidoc/
Web Book
DCS APIsjavadoc
dcs/src/main/java/
Web Book
odb User Guideasciidoc
docs/odb/
Web Book, PDF
Messages Guideasciidoc
docs/messages_guide/
Web Book, PDF
REST Reference Guideasciidoc
core/rest/src/main/asciidoc/
Web Book
REST APIsjavadoc
core/rest/src/main/java/
Web Book
SQL Reference Manualasciidoc
/docs/sql_reference/
Web Book, PDF

Source Tree Organization

 

DCS and REST

To be written.

 

All Other

All other documents share a common web-book style sheet definition, which is located in docs/css/trafodion-manuals.css.

The source tree for each manual is organized as follows:

File/DirectoryContent
pom.xml

Maven Project Object Model (POM) used to build the document.

src/

The source files used to define the document.

src/asciidocAsciidoc files for the document.
src/asciidoc/index.adoc

Main asciidoc defining the document. Includes the different chapters from the _chapters directory.

src/asciidoc/_chapters/Source files for the different chapters in the document.
images/Images used in the document.
resources/Other include materials; for example, source examples that are included with the document.
target/Build output directory. Contains the web book, the PDF file, and supporting directories.
target/index.pdfGenerated PDF version of the document.
target/images/

Copy of the images/ directory.

target/resources/

Copy of the resources/ directory.

target/site/Generated web-book directory.
target/site/index.html

Generated web book.

target/site/css/

Style sheets related to the web book. The common style sheet is included in the index.html file.

target/site/images/

Copy of the images/ directory.

target/site/resources/

Copy of the resources/ directory.


Making Changes

 

Please refer to the following web sites for guidance for information about working on asciidoc-based documentation.

 

Once you’ve made the desired changes, then do the following:

DCS and REST

  1.  Build the document using mvn clean site against the directory containing the document; for example: dcs or core/rest.

  2. Verify the content in the generated target directory. The target/index.html file provides the entry point for the web book; the target/apidocs/index.html file contains the entry point for API documentation.

Other Documentation

  1. Build the document using mvn clean site against the directory containing the document; for example:docs/client_install or docs/odb_user.

  2. Verify the content in the generated target directory. The target/index.pdf file contains the PDF version of the document while target/site/index.html contains the web-book version of the document.

 

Build Trafodion Document Tree

 

The external version of the Trafodion Document Tree is published to http://trafodion.incubator.apache.org/docs. Please refer to Publish below.

 

The build version of the Trafodion Document Tree is located in docs/target/docs, which is created when you build the Trafodion web site in Maven.

Version Directories

The Trafodion Document Tree consists of Version Directories:

Version DirectoryContentWeb Site Directory
latestKnown place for the latest version of a document.trafodion.incubator.apache.org/docs/<document-name>
<version>Release-specific version of a document.trafodion.incubator.apache.org/docs/<version>/<document-directory>

 

  • latest: Provides a well-known place for each document. This practice makes it possible to link to a document in instructional text, web sites, and other documents.
  • <version>: Provides per-release versions of documents. Previous versions are kept in the web site’s SVN repository ensuring that N versions of the documentation are available.

 

Document Directories

Each document is placed in its own Document Directory:

DocumentDocument Directory Name
Client Installation Guideclient_install
Command Interface Guidecommand_interface
Contributor Guidecontributor_guide
DCS Reference Guidedcs_reference
odb User Guideodb_user
Messages Guidemessages_guide
REST Reference Guiderest_reference
SQL Reference Manualsql_reference

The Document Directories are organized as follows. Files and sub-directories may or may not be present in the Document Directory depending on document.

File/DirectoryContent
*.pdfThe PDF version of the document. For example, Trafodion_SQL_Reference_Guide.pdf.
index.htmlThe web book version of the document. Generated by asciidoc.
apidocsAPI documentation provided as a web book. Generated by javadoc.
apidocs/index.htmlEntry point for API documentation. Generated by javadoc.
cssCSS definitions used by the web-version of the document. Populated by asciidoc.
images

Images used by the web-version of the document. Populated by asciidoc.

resourcesResource files referenced for source download etc. Populated by asciidoc.

The Document Directories are copied under the Version Directories thereby creating the web-accessible Trafodion document tree.

Populate Trafodion Document Tree

The build version of the Trafodion Document Tree is populated as follows:

DocumentInstructions
Client Installation Guide

Run maven post-site build step.

Command Interface Guide

Run maven post-site build step.

DCS Reference Guide GuideDo the following:
  • Create Version Directories, if needed.
  • Create Document Directories, if needed.
  • Copy $SQ_HOME/dcs/target/site/ to the appropriate Document Directories.
odb User Guide

Run maven post-site build step.

Messages Guide

Run maven post-site build step.

REST Reference Guide GuideDo the following:
  • Create Version Directories, if needed.
  • Create Document Directories, if needed.
  • Copy $SQ_HOME/core/rest/target/site/ to the appropriate Document Directories.
SQL Reference Manual

Run maven post-site build step.

Publish

 

Publication is done when a committer is ready to update the external web site. You do not perform these steps as part of checking in changes.

 

Do the following:

  1. Build the web site.
  2. Build the different document as described in Making Changes above.
  3. Build the Trafodion Document Tree as described in Build Trafodion Document Tree above.

 

The resulting docs/target/docs/ directory is checked into the web-site SVN branch.

 

 

 

 

 

  • No labels