trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gunnar Tapper <tapper.gun...@gmail.com>
Subject Proposal for documentation on website
Date Thu, 03 Dec 2015 02:00:31 GMT
Hi,

The Trafodion documentation is a bit challenging to deal with at the
moment. At the moment, I know of the following manuals/guides:


   - DCS Reference Guide (asciidoc) -- dcs/src/main/asciidoc
   - DCS API Docs (Javadoc)
   - REST Server Reference Guide (asciidoc) -- core/rest/src/main/asciidoc
   - REST API Docs (Javadoc)
   - Client Installation Guide (Word/PDF) -- docs/resources/docs
   - Command Interface Guide (Word/PDF) -- docs/resources/docs
   - odb User Guide (Word/PDF) -- docs/resources/docs
   - SQL Reference Guide (Word/PDF) -- docs/resources/docs

The documentation should be part of a release's source tree and, therefore,
be versioned. Further, the documentation should be available on the website.

The website is rendered into docs/target. The documents go into
docs/target/docs, which means that there will be an
incubator.trafodion.apache.org/docs directory for the website.

The content of docs/target is checked into
https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git via
manual checkout, copy, checkin and then svnpubsub, which does the actual
publication.

>From what I understand, the goal is to convert all documentation into
asciidoc providing both web and PDF version of each document. As such, I'd
believe that the web site's docs directory should be organized per version;
that is, docs/<version>. If I am correct, then I think that the preferred
layout would be:

docs
docs/<version>
docs/<version>/<document>
docs/<version>/<document>/index.html (entry point to the web version of the
document)
docs/<version>/<document>/_chapters (web version of the document; that is,
the content)
docs/<version>/<document/<document>.pdf (PDF version of the document
docs/<version>/document/apidocs/index.html (entry point to the web version
of the API docs, if they exist)

Using DCS as an example, we'd have

docs/1.3.0/dcs_reference_guide/index.html
docs/1.3.0/dcs_reference_guide/_chapters
docs/1.3.0/dcs_reference_guide/dcs_reference_guide_1_3_0.pdf
docs/1.3.0/dcs_reference_guide/apidocs/index.html

Is this an OK organization? If so, I can write up instructions for how to
copy the different documents to their target
https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git
directories.
In essence, the procedure would be:

1. Run the release build.
2. Checkout
https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git
3. Create the new docs/<version> directory.
4. Create dcs_reference_guide directory
5. Copy all files from dcs/target/site to docs/<version>/dcs_reference_guide
.
.
.
n. Move docs/target/docs/Trafodion_Client_Installation_Guide.* to
docs/<version>/client_installation_guide
.
.
.

Admittedly, this is both manual and clumsy but I think it organizes the
information in a manner that allows for future automation.

Comments? Suggestions?

-- 
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