This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.
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.
Please see here for an overview of the resources that you may need to use to create or update documentation.
Consolidated Documentation can be found in GitHub here:
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.
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 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.
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:
.. _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 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)
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
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. 18.104.22.168)
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 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.
|Write all of the words||Don't abbreviate sentences as one might when speaking. It often makes a sentence hard to read, or changes the meaning of the sentence|
|Avoid ambiguity of the object to which you are referring|
When there are more that one object in a sentence, ensure that it is explicitly stated which object is being referred to in subsequent statements.
This could be stating that either the firewall rules, the virtual routers or the scripts are being updated. This should read:
"The scripts currently updates the firewall rules on the virtual routers, the scripts will be updated to....."
Examples of bad abbreviations:
Acronyms should be in upper case:
|Capitalisation||Don't capitalise server roles mid-sentence - they are not proper names - hence use "CloudStack management server" rather than "CloudStack Management Server". |
The same goes for other components like "firewall", "network switch", "storage array", etc.
This includes 'virtual router' and 'secondary storage VM'.