Page History

The following products are used in the maintenance of the documentation:

reStructuredText

This is the authoring language that is used while write individual topics.

• QuickStart Manual
• Home Page

Sphinx

This is the document production toolkit. It is used to create documents that include the topics written in reStructuredText.

The project contains the make files for both Linux (make.sh) and Windows (make.bat) so you can use whichever operating system you wish when working on the docs.

These files run the Sphinx build and create the documentation output in the build folder. The build folder is deleted prior to each run so it should be considered as a temporary file store.

It should not be put in git.

git Repository

The documentation sources are held in git.

https://github.com/apachecloudstack/consolidated-documentation.git is the new consolidated documentation

Source Git Repository

Consolidated Documentation can be found in GitHub here:

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

The older documentation sources are held as archived source in GitHub here:

https://github.com/apache/cloudstack-docs.git is a bit of a dodge-podge of resources
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

Sphinx

http://www.sphinx-doc.org/en/master/index.html

The documentation is uses Sphinx, which provides the structure and hierarchy of the documentation. It is the engine which renders the source text into HTML, PDF and ePub formats.  You can install and use Sphinx to build the documentation to see what it will look like before pushing a change, but it isn't required.

Read The Docs

https://readthedocs.org

The CloudStack documentation is built using the ReadTheDocs service. ReadTheDocs takes the source text and runs it through the Sphinx engine to produce the documentation and also hosts the output.  Access is not strictly required in order to write/update the source documentation. Only to build the documentation for a new version.

If you would like access, please contact the dev list.

reStructuredText

This is the authoring language that is used while write individual topics.  reStructured text (RST) is the markup language that allows us to denote, headings, sections, bullets, bold text, italics etc.

• QuickStart Manual
• Home Page

Here are some great resources to get started with reStructured text in a Sphinx context  

• http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
• http://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html

...

Rest Editor for Eclipse

This is the plug-in that supports the maintenance and production of documents in Eclipse.

...

It can be downloaded from the Eclipse Marketplace as the Rest Editor 1.0.5

Online RST Editors/Viewers

http://rst.ninjs.org/ - Helpful to have a semi-WYSIWYG experience.  The 'Nature' theme most closely resembles the theme used in the CloudStack documentation

Open Office for drawing creation

The drawings for the new documentation are created using Open Office Draw.

...

The sources for the drawings in the previous manual are lost.

VRT Network drawing extensions

VRT network drawing extension for Open Office are used to create the drawings. This may be downoaded and added to OpenOffice as an extension. The symbols will appear in Draw's Gallery.

There is an explanation about how to use them on Artifact Software's technical blog.

Logos 

There are a number of resources related to trademarks and other graphics.

...