The page is about writing or updating the source 'text' of the CloudStack documentation. If you are interested in publish (updating) the public visible rendering of the source, please see the Publishing Documentation Via Read The Docs guide.

Resources

Please see here for an overview of the resources that you may need to use to create or update documentation.

Documentation Source Repos

Consolidated Documentation can be found in GitHub here:

https://github.com/apache/cloudstack-documentation/

What and Why Documentation

The CloudStack community is great at adding new features to CloudStack that make it more useable and flexible with every release.  However, it is almost just as important to inform the users of CloudStack that these features exist and how to use them.  Especially when features have been changed to include new functionality or cause changes the previous way of working.

When writing documentation, one must put oneself in the shoes of the user is trying to use CloudStack to achieve an objective or is exploring cloudstack to understand what it does and how it does it.  Many users will not have the wider background of either the developer or the document writer, and therefore will need clear and concise step-by-step instructions explaining  what a feature does and how to use it.

Sphinx

The documentation in written in 'Sphinx'. For small updates, you don't need to be too familiar with Sphinx, but Sphinx gives the documentation its shape and hierarchy and looks after links and references between documents or sections. If you are trying to relate one section to another, or create new sections, which would then be visible as a separate section in the 'contents' then you will need to look at Sphinx documentation rather than RST (see below).

reStructuredText

The authoring language that is used in the ACS CloudStack Documentation is reStructuredText (RST).  The authoring language allows the writer to denote sections of text as headings or paragraphs, in bold or italics. as well underling or 

the resources page has some links to help you getting started writing in that format.  

Read The Docs

Rather than an instruction, read the docs is a service which publishes versioned documentation.  It is linked to the cloudstack Github documentation repositories, and will build the documentation in the form seen at 'http://docs.cloudstack.apache.org/' from the source 'text' which we commit to Github.  Read the docs applies a theme to the source text, as well as generating navigation menus for viewers of the site.

Writing Documentation Basics

Workflow

Here are the steps to create a PR the 

1. Clone the documentation repo
2. Switch to the correct branch (master for a future version)
3. Update (or add) the section that you're working on.
4. Double check the reStructured Text using a proofing tool (see resources) to ensure that it looks as you'd expect.
5. Commit your changes locally
6. Create a PR from your repo to the ACS documentation repo
7. Ping people to get their attention to get it merged.
8. (Possibly ping people again if required)
9. Remember to merge to master AND the release branch if you've documented something in a release branch that will also be applicable to new versions of CloudStack as well. 

Basic Syntax

Headings and Sections

To denote a heading or section RST uses underlining on the next line with a given character, the number of characters in the underline should be at least the same number of characters as text above.

This is an RST Heading
======================

To denote different levels of heading, you change the character used.  You must be consistent ie always use the same character for heading 2. While which character you use for what is not mandated, there is a guide to these headings here:

http://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html

References/Bookmarks

.. _this-is-link-to-a-heading               <-- marker
:ref:`this-is-link-to-a-heading`            <-- reference to marker

If you are linking to a 'bookmark' that does not precede a header you have to add a caption of your own:

.. _this-is-link-to-a-bookmark                                                  <-- marker
:ref:`section about bookmarks <this-is-link-to-a-bookmark>`                     <-- reference to marker + caption

Images

images are inserted by adding the required image file to /_static/images/ in the repo and linking as follows:

.. image:: /_static/images/zone-overview.png

or if you want to control positioning and add a caption, use a figure.

.. figure:: /_static/images/zone-overview.png

Code Blocks

to add a code block use the flowing syntax (note the indentation)

.. code-block:: bash

   cloudstack-setup-database cloud:cloud@localhost --deploy-as=root:password@localhost

If the block contains a substitution, use parsed-literal (although watch out for special characters)

.. parsed-literal::
   yum install cloudstack-|version|

Includes

You can modularise the source text by using include to stop any one document becoming too bloated

.. include:: _sysvm_restart.rst

Creating Diagrams

TODO

Advanced Information

Releases and Versions

The conf.py file in the root of the documentation holds two variables (among other things), release and version.

Version is the short 'version' of CloudStack that the documentation is referring to (ie 4.11)

Release is the long 'version' of CloudStack that the documentation is referring to (ie. 4.11.1.0)

These are referenced in the source text as |version| and |release|.  Updating these in the conf.py should update the vast majority of references to versions/releases in the compiled docs.

Global Substitutions

In the root of the documentation source, there is a file called _global.rst.  This file is referred to in conf.py and is appended to every page automatically by Sphinx.  There is no need to explicitly include this file in the source pages.

This file contains substitutions which can be used globally, including URLs to the 'current' system VM templates and URL of the main CloudStack logo.  Where document writers find a reference which is often repeated and/or needs to be changed from time to time, it would be helpful if they could move the substitution to the global file and update the pointers throughout the documentation.

When writing documentation it is advisable to check the global substitution file 1st to know when substitutions are made globally rather than locally.

Documentation Writing Guidelines