...

https://github.com/apache/cloudstack-documentation/The Documentation for CloudStack is currently split across three separate repositories, which are maintained over three unconnected projects in the Read The Docs service.

https://github.com/apache/cloudstack-docs-install.git is the install guide

https://github.com/apache/cloudstack-docs-admin.git is the current admin manual.

https://github.com/apache/cloudstack-docs-rn.git is the release notes for individual releases

What and Why Documentation

...

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/projects/cloudstack-administration/en/latest/' 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.

...

1. Clone the documentation repo that you wish to update
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 .rst 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 against the repo that you've updatedfrom 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

...

.. _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:

...

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

...