...
Consolidated Documentation can be found in GitHub here:
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
...
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.
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).
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.
rather 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.
The authoring language that is used in the ACS CloudStack Documentation is reStructuredText (RST), the resources page has some links to help you getting started writing in that format.
Here are the steps to create a PR the
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
.. _this-is-link-to-a-heading
:ref;`this-is-link-to-a-heading`
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
:ref:`section about bookmarks <this-is-link-to-a-bookmark>`
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
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|
You can modularise the source text by using include to stop any one document becoming too bloated
.. include:: _sysvm_restart.rst
TODO
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.
In the route 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.
...