Excerpt |
---|
Contains information about how to add and modify Trafodion documentation that is part of the Trafodion source tree. This documentation is written in asciidoc. |
...
Table of Contents | ||||
---|---|---|---|---|
|
...
Source
Documents do not include version information as part of the file name.
Source Location
Document | Source Format | Source Tree | Output Format |
---|---|---|---|
Client Installation Guide | asciidoc | docs/client_install/ | Web Book, PDF |
Command Interface Guide | asciidoc | docs/command_interface/ | Web Book, PDF |
Contributor Guide | asciidoc | docs/contributor_guide/ | Web Book, PDF |
DCS Reference Guide | asciidoc | dcs/src/main/asciidoc/ | Web Book |
DCS APIs | javadoc | dcs/src/main/java/ | Web Book |
odb User Guide | asciidoc | docs/odb/ | Web Book, PDF |
Messages Guide | asciidoc | docs/messages_guide/ | Web Book, PDF |
REST Reference Guide | asciidoc | core/rest/src/main/asciidoc/ | Web Book |
REST APIs | javadoc | core/rest/src/main/java/ | Web Book |
SQL Reference Manual | asciidoc | /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:
...
Anchor modifying-documentation-making-changes modifying-documentation-making-changes
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:
Building an Individual Document
- Be sure to source env.sh, so that the TRAFODION_VER environment variable is defined.
- Build the document using
mvn clean site
in the directory containing the document; for example:dcs
or docs/odb_user.- If you have not previously built the JDBC drivers, the DCS and REST documents will give spurious errors about missing that dependency. The documents can be built fine, skipping over that dependency using
mvn -P'!jdbc' site
.
- If you have not previously built the JDBC drivers, the DCS and REST documents will give spurious errors about missing that dependency. The documents can be built fine, skipping over that dependency using
Verify the content in the generated
target
directory.The
target/index.html
file provides the entry point for the web book.For those that have API documentation, the
target/apidocs/index.html
file is the entry point.- For those that have PDF, the
target/index.pdf
file contains the PDF version of the document.
Building the Entire Website, including Documents
- Be sure to source env.sh, so that the TRAFODION_VER environment variable is defined.
- Build everything using
mvn clean post-site
in the top-level directory.- As above, to skip over JDBC dependency, use
mvn -P'!jdbc' post-site
. - If run into outofmemory Java exception, try "export MAVEN_OPTS="-Xmx2048m -Xms1024m -XX:MaxPermSize=512m"
- As above, to skip over JDBC dependency, use
- Verify the contents in the generated
docs/target
directory.- All documents are in
docs/target/docs
directory.
- All documents are in
Anchor | ||||
---|---|---|---|---|
|
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 Directory | Content | Web Site Directory |
---|---|---|
latest | Known 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:
...
Anchor modify-documentation-publish modify-documentation-publish
Publish
Info |
---|
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. Publishing steps are documented in the "Merge Changes" section. |
Refer to Website Publishing for how the website and documents get published.