trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gunnar Tapper <tapper.gun...@gmail.com>
Subject Re: Proposal for documentation on website
Date Thu, 03 Dec 2015 07:13:37 GMT
I uploaded a new version of the web site, which documents and implements
this proposal: https://drive.google.com/open?id=0BxlwNhWxn8iTR1lSd2JEV1ZIZDg

I haven't generated the REST documentation but both the Documentation and
Contributing menus should give you a good idea how this works.

Thanks,

Gunnar

On Wed, Dec 2, 2015 at 7:00 PM, Gunnar Tapper <tapper.gunnar@gmail.com>
wrote:

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



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