Writing style guide¶

Overview¶

This guide describes the writing style for the OpenStack Charms documentation sources.

Note

The OpenStack Charms project also abides by these guides:

However, in cases of disagreement or ambiguity, the current document takes precedence.

General guidelines¶

Juju application names are not formatted:
- “the nova-compute application”
- “the nova-compute charm”
- “the nova-compute unit”
Cited bugs are expressed as hyperlinks and, depending on Launchpad or GitHub bug trackers, are of the form:
- “see bug LP #123456”
- “tracked in bug GH #173”

Use monospace format for:
- unit names: “the nova-compute/3 unit”
- action names: “the list-disks action”
- references to utilities/programs: “like haproxy or curl”
- paths: “in the /etc/glance directory”
- command options: “the --force command option”
- charm configuration options: “the data-port option”
Use a maximum line length of 79 characters.
Use single quotes for values: “the option’s value is ‘br-ex:eth1’”.
Use bold and italics very sparingly.
Use single spaces between sentences.
Use hyperlink labels at the bottom of a page.

Admonishments¶

An admonishment should contain drop-in, self-sufficient text. That is, it should not depend on the main-body (surrounding) text to be intelligible. In this way, if the admonishment becomes no longer applicable, removing it will not adversely affect the logic of the surrounding text.

Capitalisation¶

Capitalisation should be minimised:

Use a capital letter for just the first word of all section headers
Use capital letters for any proper nouns or acronyms, as usual
OpenStack services such as Nova
Project names like HAProxy or OpenStack

Transient information¶

Be mindful of including information that is expected to become out of date, such as citing bugs or listing things that will surely change. It might be better to simply omit some information. For instance, do not start a list of versions thinking that it will be maintained by someone. To avoid:

Firefly is available in Trusty, Hammer is in Trusty-Juno (end of life),
Trusty-Kilo, Trusty-Liberty, and Jewel is available in Trusty-Mitaka.

The use of temporal expressions such as “not yet”, “currently”, and “at the time of writing”, or closely related status terms such as “experimental”, should be avoided entirely. To avoid:

The charm should not yet be used in the following scenarios...

... but note that this is an experimental feature.

Release notes are an exception as the temporal context is understood:

The charm now supports feature X...

If at all possible, simply give numbers (e.g. versions, dates) to guide a reader, but do not hardcode versions into instructions. Explain with words and include versions only as part of an example command.

Important

If transient information is categorically needed then express it with an admonishment. The use of admonishments also makes temporal information much easier to identify during documentation reviews.

Whitespace¶

All extra whitespace should be removed, especially at the end of lines.

Warning

Two trailing spaces is valid Markdown; it forces a carriage return. This is very rarely required and should be avoided whenever possible.

Snippets¶

Some messaging is used repeatedly due to situations that arise regularly. This section is an attempt at making a consistent set of snippets for such cases.

Preview charms or functionality¶

Use an informational admonishment to convey tech-preview status for a charm, or functionality for an existing charm:

The MySQL 8 charms are in a tech-preview state and are ready for testing.
They are not production-ready.

Charmed Swift global cluster functionality is in a tech-preview state and is
ready for testing. It is not production-ready.

Version requirements or limitations¶

Use an informational admonishment to convey a software requirement or limitation for a charm, or functionality for an existing charm:

BlueStore compression is supported starting with Ceph Mimic.

Command syntax¶

The following deploy or add-unit command syntax and ordering of options should be observed:

juju deploy -n <X> --to <Y> --config <option=Z> ...

juju add-unit -n <X> --to <Y> --config <option=Z> ...

Multi-line commands should have their extra lines indented by three spaces:

openstack role add --user 1ea06b07c73149ca9c6753e07c30383a \
   --project Project1 Member

reStructuredText formatting¶

RST - General formatting¶

Italics - use single asterisks:

*this is in italics*

Bold - use double asterisks:

**this is in bold**

Monospace - use double backticks:

the ``--force`` option may help

RST - Section headers¶

There are five section headers:

=======================
H1 (double equal signs)
=======================

H2 (dashes)
-----------

H3 (tildes)
~~~~~~~~~~~

H4 (carets)
^^^^^^^^^^^

H5 (dots)
.........

RST - Inline commands¶

For commands or utilities that are mentioned in a sentence use the :command: directive:

You can type the :command:`juju status` command to get an overview of the
model.

The :command:`openstack` client is the preferred tool.

RST - Linking to an external site¶

see the `Juju documentation`_ for more details ...

.
.

The issue is tracked in bug `LP #1846279`_ ...

.
.
<bottom of page>

.. LINKS
.. _Juju documentation: https://juju.is/docs

.. BUGS
.. _LP #1846279: https://bugs.launchpad.net/postgresql-charm/+bug/1846279

RST - Linking to a page in the doc set¶

Assuming that the destination document is install-maas.rst then in the source document:

In the :doc:`previous section <install-maas>`

The linking is relative. If the destination document was in the parent directory:

In the :doc:`previous section <../install-maas>`

RST - Linking to a location within the current page¶

Section headers are valid targets by default (implicit links).

Deploy OpenStack
~~~~~~~~~~~~~~~~

.
.

In the `Deploy OpenStack`_ step above

First create a target in order to link to a non-header. Use one of three methods:

In the example_ below

or in `example #5`_

or in the :ref:`Crisis situation <example_crisis>` example

.
.

.. _example:

.
.

.. _example #5:

.
.

.. _example_crisis:

RST - Linking to a location within a page in the doc set¶

In the source document:

during the :ref:`Install MAAS <install_maas>` step on the previous page

In the destination document insert the target code (typically above a section header):

.. _install_maas:

Install MAAS
------------

RST - Admonishments¶

Admonishment types and their purpose:

Type	Purpose
`tip`	to provide auxiliary information
`note`	to inform
`important`	to accentuate
`caution`	to draw special attention to
`warning`	to warn about potential breakage or data loss

Syntax:

.. <type>::

   text goes here. text goes here. text goes here. text goes here. text goes
   maintain the alignment.

The text is left-aligned with the admonishment type.

Example:

.. note::

   This is a note.

RST - Code blocks¶

Syntax for code blocks:

.. code-block:: <type>

   something goes here

The block is left-aligned with ‘code-block’.

Code block types:

Type	Purpose
`none`	console input
`console`	console output
`python`, `bash`, `yaml`	code snippets/scripts
`ini`	miscellaneous file content

console input¶

The following command shows the relations:

.. code-block:: none

   juju status --relations

console output¶

Sample output of the last command is:

.. code-block:: console

   Name            Version      Rev    Tracking        Publisher    Notes
   charm           2.8.2        609    latest/stable   canonical✓   classic
   charmcraft      1.4.0        761    latest/stable   canonical✓   classic

code snippet¶

This bit of Python will do the trick:

.. code-block:: python

   def anagram(first, second):
    return Counter(first) == Counter(second)

Do not use the bash type for simple command invocations.

miscellaneous file contents¶

The contents of file ``/etc/ec2_version`` is:

.. code-block:: ini

   Ubuntu 20.04.1 LTS (Focal)

RST - Lists¶

Add a blank line between each item if any list items are multi-lined.

Unordered list¶

* First item. Align any word-wrapped lines
  like this.

* Second item

Nested unordered list¶

For nested lists, indent items so they align with the parent text:

* First item

  * Nested item
  * Nested item

* First item

  * Nested item
  * Nested item

Ordered list¶

#. First item
#. Second item

Nested ordered list¶

For nested lists, indent items so they align with the parent text:

#. First item

   #. Nested item
   #. Nested item

#. First item

   #. Nested item
   #. Nested item

RST - Definitions¶

To define a term, indent its definition by two spaces:

Charm upgrade
  An upgrade of the charm software which is used to deploy and manage
  OpenStack. This includes charms that manage applications which are not
  technically part of the OpenStack project.

RST - Images and figures¶

To insert an image or a figure:

.. image:: <relative/path/to/image.png>
   :<property>
   :<property>

See RST documentation on images and figures for details.

Markdown formatting¶

MD - General formatting¶

Italics - use single asterisks:

*this is in italics*

Bold - use double asterisks:

**this is in bold**

Monospace - use single backticks:

the `--force` option may help

MD - Section headers¶

There are five section headers:

# H1

## H2

### H3

#### H4

##### H5

MD - Inline commands¶

For commands or utilities that are mentioned in a sentence use monospace:

You can type the `juju status` command to get an overview of the model.

The `openstack` client is the preferred tool.

MD - Linking to an external site¶

The [OpenStack Charms Deployment Guide][cdg] ...

.
.

... in the [OpenStack Charm Guide][cg] ...

.
.

See bug [LP #1862392][lp-bug-1862392] ...

.
.
<bottom of page>

<!-- LINKS -->

[cg]: https://docs.openstack.org/charm-guide
[cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide
[lp-bug-1862392]: https://bugs.launchpad.net/charm-cinder/+bug/1862392

MD - Linking to a header within the current page¶

See section [Availability zones][anchor-az]...

.
.

## Availability zones

.
.
<bottom of page>

<!-- LINKS -->

[anchor-az]: #availability-zones

MD - Admonishments¶

Markdown itself does not have admonishment types as such. Implement an equivalent RST admonishment as a Markdown quote:

Type	Purpose
`Tip`	to provide auxiliary information
`Note`	to inform
`Important`	to accentuate
`Caution`	to draw special attention to
`Warning`	to warn about potential breakage or data loss

Syntax:

> **<type>**: text goes here. text goes here. text goes here. text goes here
  maintain the alignment.

The text is left-aligned with the asterisks.

Example:

> **Note**: The 'ceph-rbd-mirror' charm addresses only one specific element
  in datacentre redundancy.

MD - Code blocks¶

console input¶

Indent four spaces:

The following command shows the relations:

    juju status --relations

console output¶

Indent four spaces:

Sample output of the last command is:

    Name              Version               Rev    Tracking        Publisher    Notes
    charm             2.8.2                 609    latest/stable   canonical✓   classic
    charmcraft        1.4.0                 761    latest/stable   canonical✓   classic

code snippet¶

Use syntax highlighting for code snippets/scripts using backticks and a language type:

python
bash
yaml

Do not use the bash type for simple command invocations.

Example:

This bit of Python will do the trick:

```python
   import random

   def flip():
       if random.randint(0,1) == 0:
           return "heads"
       else:
           return "tails"
         def anagram(first, second):
          return Counter(first) == Counter(second)
```

Use your prerogative for indentation.

miscellaneous file contents¶

Indent file contents with four spaces:

The contents of file ``/etc/ec2_version`` is:

    Ubuntu 20.04.1 LTS (Focal)

MD - Lists¶

Add a blank line between each item if any list items are multi-lined.

Unordered list¶

* First item. Align any word-wrapped lines
  like this.

* Second item

Nested unordered list¶

Indent nested items with four spaces:

* First item
    * Nested item

Ordered list¶

1. First item
1. Second item

Nested ordered list¶

Indent nested items with four spaces:

1. First item
    1. Nested item

MD - Images¶

A regular image:

![alt-text][image]

.
.

<bottom of page>

<!-- LINKS -->

[image]: path to image

An image as hyperlink:

[![alt-text][image]][image-target-link]

.
.

<bottom of page>

<!-- LINKS -->

[image]: path to image
[image-target-link]: link URL

Writing style guide

Writing style guide¶

Overview¶

General guidelines¶

Admonishments¶

Capitalisation¶

Transient information¶

Whitespace¶

Snippets¶

Preview charms or functionality¶

Version requirements or limitations¶

Command syntax¶

reStructuredText formatting¶

RST - General formatting¶

RST - Section headers¶

RST - Inline commands¶

RST - Linking to an external site¶

RST - Linking to a page in the doc set¶

RST - Linking to a location within the current page¶

RST - Linking to a location within a page in the doc set¶

RST - Admonishments¶

RST - Code blocks¶

console input¶

console output¶

code snippet¶

miscellaneous file contents¶

RST - Lists¶

Unordered list¶

Nested unordered list¶

Ordered list¶

Nested ordered list¶

RST - Definitions¶

RST - Images and figures¶

Markdown formatting¶

MD - General formatting¶

MD - Section headers¶

MD - Inline commands¶

MD - Linking to an external site¶

MD - Linking to a header within the current page¶

MD - Admonishments¶

MD - Code blocks¶

console input¶

console output¶

code snippet¶

miscellaneous file contents¶

MD - Lists¶

Unordered list¶

Nested unordered list¶

Ordered list¶

Nested ordered list¶

MD - Images¶

charm-guide yoga

Page Contents