Writing &PRODUCT; Documentation

Writing &PRODUCT; Documentation &PRODUCT; 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: ]]> All these xml files are written in DocBook format. 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: Preparing and Building &PRODUCT; Documentation 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 ]]> 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: Building &PRODUCT; Documentation To build a specific guide, go to the source tree of the documentation in /docs and identify the guide you want to build. Currenlty there are four guides plus the release notes, all defined in publican configuration files: publican-adminguide.cfg publican-devguide.cfg publican-installation.cfg publican-plugin-niciranvp.cfg publican-release-notes.cfg To build the Developer guide for example, do the following: publican build --config=publican-devguide.cfg --formats=pdf --langs=en-US 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.