7.3. Writing CloudStack Documentation

CloudStack documentation is written in DocBook xml format. Each guide defined with a publican configuration file refers to a DocBook book.

These books are defined in xml files in docs/en-US, for instance if we look at the Developers guide, its configuration file contains:

        xml_lang: en-US
        type: Book
        docname: Developers_Guide
        brand: cloudstack
        chunk_first: 1
        chunk_section_depth: 1

The docname key gives you the basename of the DocBook file located in the en-US directory that contains the description of the book.

Looking closely at Developers_Guide.xml we see that it contains book tags and several references to other xml files. These are the chapters of the book, currently they are:

    
        <xi:include href="concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="building-with-maven.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="developer-introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="whats-new.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="api-calls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="working-with-usage-data.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="working-with-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="event-types.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="alerts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="time-zones.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />

All these xml files are written in DocBook format.

Nota

DocBook format is well documented, refer to the documentation for any questions about DocBook tags

When writing documentation, you therefore need to located the book,chapter and section of the content you want to write/correct. Or create a new book,chapter,section.

You will then learn much more about DocBook tagging. In order to write this chapter about documentation, I added the working-with-documentation.xmlfile describing a chapter in the Developer book and I created several sections within that chapter like so:

    
        <chapter id="working-with-documentation">
            <title>Preparing and Building CloudStack Documentation</title>
            <para>This chapter describes how to install publican, how to write new documentation and build a guide as well as how to build a translated version of the documentation using transifex</para>
            <xi:include href="installing-publican.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
            <xi:include href="building-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
            <xi:include href="writing-new-documentation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
            <xi:include href="building-translation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
        </chapter>

Note the id witin the chapter tag, it represents the basename of the xml file describing the chapter.

For translation purposes it is important that this basename be less than 50 characters long.

This chapter also refers to xml files which contains each section. While you could embed the sections directly in the chapter file and as a matter of fact also write the chapters within a single book file. Breaking things up in smaller files at the granularity of the section, allows us to re-use any section to build different books.

For completeness here is an example of a section:

    
        <section id="building-documentation">
            <title>Building CloudStack Documentation</title>
            <para>To build a specific guide, go to the source tree of the documentation in /docs and identify the guide you want to build.</para>
            <para>Currently there are four guides plus the release notes, all defined in publican configuration files:</para>
            <programlisting>
               publican-adminguide.cfg
               publican-devguide.cfg
               publican-installation.cfg
               publican-plugin-niciranvp.cfg
               publican-release-notes.cfg
            </programlisting>
            <para>To build the Developer guide for example, do the following:</para>
            <programlisting>publican build --config=publican-devguide.cfg --formats=pdf --langs=en-US</programlisting>
            <para>A pdf file will be created in tmp/en-US/pdf, you may choose to build the guide in a different format like html. In that case just replace the format value.</para>
        </section>

Happy Publicating and DocBooking.