From 455bbf5526d7a503176044c457a33be2a1339c6c Mon Sep 17 00:00:00 2001 From: Peter Matulis Date: Wed, 27 Jul 2022 13:12:44 -0400 Subject: [PATCH] Refactor doc contrib pages Put RST and MD formatting guidance on separate pages Rename page doc-style-guide to styleguide Add/modify text/links as a consequence of the refactor. Fix two broken links in order for the project to build. Change-Id: If91f3d994458bf68092d684c7201985055ea4972 --- .../admin/networking/load-balancing.rst | 3 +- doc/source/admin/networking/ovn.rst | 5 +- .../doc-contrib/adding-new-content.rst | 6 +- .../community/doc-contrib/doc-style-guide.rst | 815 ------------------ doc/source/community/doc-contrib/index.rst | 2 +- doc/source/community/doc-contrib/md.rst | 284 ++++++ doc/source/community/doc-contrib/rst.rst | 360 ++++++++ .../community/doc-contrib/styleguide.rst | 190 ++++ .../charm-readme-template.rst | 4 +- 9 files changed, 843 insertions(+), 826 deletions(-) delete mode 100644 doc/source/community/doc-contrib/doc-style-guide.rst create mode 100644 doc/source/community/doc-contrib/md.rst create mode 100644 doc/source/community/doc-contrib/rst.rst create mode 100644 doc/source/community/doc-contrib/styleguide.rst diff --git a/doc/source/admin/networking/load-balancing.rst b/doc/source/admin/networking/load-balancing.rst index 08d73315..6cedbdaf 100644 --- a/doc/source/admin/networking/load-balancing.rst +++ b/doc/source/admin/networking/load-balancing.rst @@ -40,8 +40,7 @@ load balancers. Barbican, in turn, uses Vault to securely store that data. .. note:: For Vault deployment instructions see the `vault charm`_. For certificate - management information read the :doc:`cdg:app-certificate-management` - page of the Deploy Guide. + management information read the :doc:`../security/tls` page. To deploy Barbican: diff --git a/doc/source/admin/networking/ovn.rst b/doc/source/admin/networking/ovn.rst index 8ca290b8..d87dba0b 100644 --- a/doc/source/admin/networking/ovn.rst +++ b/doc/source/admin/networking/ovn.rst @@ -40,8 +40,7 @@ Certificates must be managed by Vault. .. note:: For Vault deployment instructions see the `vault charm`_. For certificate - management information read the :doc:`cdg:app-certificate-management` - page of the Deploy Guide. + management information read the :doc:`../security/tls` page. To deploy OVN: @@ -105,7 +104,7 @@ for use with hardware offloading and make them available to OpenStack. This feature is to be considered Tech Preview. OVN has more stringent requirements for match/action support in the hardware than for example Neutron ML2+OVS. Make sure to acquire hardware with appropriate support. - + Depending on hardware vendor, it may be required to install third party drivers (DKMS) in order to successfully use this feature. diff --git a/doc/source/community/doc-contrib/adding-new-content.rst b/doc/source/community/doc-contrib/adding-new-content.rst index dfa93178..f2423702 100644 --- a/doc/source/community/doc-contrib/adding-new-content.rst +++ b/doc/source/community/doc-contrib/adding-new-content.rst @@ -130,9 +130,9 @@ viewed in the Charmhub. See the `keystone charm Docs tab`_ for an example. Writing style ~~~~~~~~~~~~~ -Please use the :doc:`style guide ` when creating content. -Documentation is more clearly understood by users and developers alike when it -is implemented in a consistent manner. +Please use the :doc:`styleguide` when creating content. Documentation is more +clearly understood by users and developers alike when it is implemented in a +consistent manner. Technical accuracy ~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/community/doc-contrib/doc-style-guide.rst b/doc/source/community/doc-contrib/doc-style-guide.rst deleted file mode 100644 index c26b1ac4..00000000 --- a/doc/source/community/doc-contrib/doc-style-guide.rst +++ /dev/null @@ -1,815 +0,0 @@ -=================== -Writing style guide -=================== - -Overview --------- - -This guide describes the writing style for the OpenStack Charms documentation -:ref:`sources `. - -.. note:: - - The OpenStack Charms project also abides by these guides: - - * the `OpenStack documentation contributor guide`_ - * the `Ubuntu documentation style guide`_ - - 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`_" - -.. _LP #123456: https://pad.lv/123456 -.. _GH #173: https://github.com/juju-solutions/layer-basic/issues/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: - -.. code-block:: none - - 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: - -.. code-block:: none - - 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: - -.. code-block:: none - - 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: - -.. code-block:: none - - 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: - -.. code-block:: none - - BlueStore compression is supported starting with Ceph Mimic. - -Command syntax --------------- - -The following :command:`deploy` or :command:`add-unit` command syntax and -ordering of options should be observed: - -.. code-block:: none - - juju deploy -n --to --config ... - - juju add-unit -n --to --config ... - -Multi-line commands should have their extra lines indented by three spaces: - -.. code-block:: none - - openstack role add --user 1ea06b07c73149ca9c6753e07c30383a \ - --project Project1 Member - -reStructuredText formatting ---------------------------- - -RST - General formatting -~~~~~~~~~~~~~~~~~~~~~~~~ - -Italics - use single asterisks: - -.. code-block:: none - - *this is in italics* - -Bold - use double asterisks: - -.. code-block:: none - - **this is in bold** - -Monospace - use double backticks: - -.. code-block:: none - - the ``--force`` option may help - -RST - Section headers -~~~~~~~~~~~~~~~~~~~~~ - -There are five section headers: - -.. code-block:: none - - ======================= - 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: - -.. code-block:: none - - 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - - see the `Juju documentation`_ for more details ... - - . - . - - The issue is tracked in bug `LP #1846279`_ ... - - . - . - - - .. 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: - -.. code-block:: none - - In the :doc:`previous section ` - -The linking is relative. If the destination document was in the parent -directory: - -.. code-block:: none - - 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). - -.. code-block:: none - - 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: - -.. code-block:: none - - In the example_ below - - or in `example #5`_ - - or in the :ref:`Crisis situation ` example - - . - . - - .. _example: - - . - . - - .. _example #5: - - . - . - - .. _example_crisis: - -RST - Linking to a location within a page in the doc set -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In the source document: - -.. code-block:: none - - during the :ref:`Install MAAS ` step on the previous page - -In the destination document insert the target code (typically above a section -header): - -.. code-block:: none - - .. _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: - -.. code-block:: none - - .. :: - - 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: - -.. code-block:: none - - .. note:: - - This is a note. - -RST - Code blocks -~~~~~~~~~~~~~~~~~ - -Syntax for code blocks: - -.. code-block:: none - - .. code-block:: - - 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 -^^^^^^^^^^^^^ - -.. code-block:: none - - The following command shows the relations: - - .. code-block:: none - - juju status --relations - -console output -^^^^^^^^^^^^^^ - -.. code-block:: none - - 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 -^^^^^^^^^^^^ - -.. code-block:: none - - 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 -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - 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 -^^^^^^^^^^^^^^ - -.. code-block:: none - - * 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: - -.. code-block:: none - - * First item - - * Nested item - * Nested item - - * First item - - * Nested item - * Nested item - -Ordered list -^^^^^^^^^^^^ - -.. code-block:: none - - #. First item - #. Second item - -Nested ordered list -^^^^^^^^^^^^^^^^^^^ - -For nested lists, indent items so they align with the parent text: - -.. code-block:: none - - #. First item - - #. Nested item - #. Nested item - - #. First item - - #. Nested item - #. Nested item - -RST - Definitions -~~~~~~~~~~~~~~~~~ - -To define a term, indent its definition by two spaces: - -.. code-block:: none - - 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: - -.. code-block:: none - - .. image:: - : - : - -See `RST documentation on images and figures`_ for details. - -Markdown formatting -------------------- - -MD - General formatting -~~~~~~~~~~~~~~~~~~~~~~~ - -Italics - use single asterisks: - -.. code-block:: none - - *this is in italics* - -Bold - use double asterisks: - -.. code-block:: none - - **this is in bold** - -Monospace - use single backticks: - -.. code-block:: none - - the `--force` option may help - -MD - Section headers -~~~~~~~~~~~~~~~~~~~~ - -There are five section headers: - -.. code-block:: none - - # H1 - - ## H2 - - ### H3 - - #### H4 - - ##### H5 - -MD - Inline commands -~~~~~~~~~~~~~~~~~~~~ - -For commands or utilities that are mentioned in a sentence use monospace: - -.. code-block:: none - - 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - - The [OpenStack Charms Deployment Guide][cdg] ... - - . - . - - ... in the [OpenStack Charm Guide][cg] ... - - . - . - - See bug [LP #1862392][lp-bug-1862392] ... - - . - . - - - - - [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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: none - - See section [Availability zones][anchor-az]... - - . - . - - ## Availability zones - - . - . - - - - - [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: - -.. code-block:: none - - > ****: text goes here. text goes here. text goes here. text goes here - maintain the alignment. - -The text is left-aligned with the asterisks. - -Example: - -.. code-block:: none - - > **Note**: The 'ceph-rbd-mirror' charm addresses only one specific element - in datacentre redundancy. - -MD - Code blocks -~~~~~~~~~~~~~~~~ - -console input -^^^^^^^^^^^^^ - -Indent four spaces: - -.. code-block:: none - - The following command shows the relations: - - juju status --relations - -console output -^^^^^^^^^^^^^^ - -Indent four spaces: - -.. code-block:: none - - 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: - -.. code-block:: none - - 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: - -.. code-block:: none - - 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 -^^^^^^^^^^^^^^ - -.. code-block:: none - - * First item. Align any word-wrapped lines - like this. - - * Second item - -Nested unordered list -^^^^^^^^^^^^^^^^^^^^^ - -Indent nested items with four spaces: - -.. code-block:: none - - * First item - * Nested item - -Ordered list -^^^^^^^^^^^^ - -.. code-block:: none - - 1. First item - 1. Second item - -Nested ordered list -^^^^^^^^^^^^^^^^^^^ - -Indent nested items with four spaces: - -.. code-block:: none - - 1. First item - 1. Nested item - -MD - Images -~~~~~~~~~~~ - -A regular image: - -.. code-block:: none - - ![alt-text][image] - - . - . - - - - - - [image]: path to image - -An image as hyperlink: - -.. code-block:: none - - [![alt-text][image]][image-target-link] - - . - . - - - - - - [image]: path to image - [image-target-link]: link URL - -.. LINKS -.. _Ubuntu documentation style guide: https://docs.ubuntu.com/styleguide/en -.. _OpenStack documentation contributor guide: https://docs.openstack.org/doc-contrib-guide -.. _Sphinx: https://www.sphinx-doc.org/en/master/index.html -.. _RST documentation on images and figures: https://docutils.sourceforge.io/docs/ref/rst/directives.html#images diff --git a/doc/source/community/doc-contrib/index.rst b/doc/source/community/doc-contrib/index.rst index 0e59c764..cdcefa7d 100644 --- a/doc/source/community/doc-contrib/index.rst +++ b/doc/source/community/doc-contrib/index.rst @@ -13,7 +13,7 @@ addition of new content. The following resources are available: :maxdepth: 1 adding-new-content - doc-style-guide + styleguide Below is a summary of all documentation sources for the OpenStack Charms project. diff --git a/doc/source/community/doc-contrib/md.rst b/doc/source/community/doc-contrib/md.rst new file mode 100644 index 00000000..66b01591 --- /dev/null +++ b/doc/source/community/doc-contrib/md.rst @@ -0,0 +1,284 @@ +======== +Markdown +======== + +This page provides guidance when working with the MD format. + +General formatting +------------------ + +Italics - use single asterisks: + +.. code-block:: none + + *this is in italics* + +Bold - use double asterisks: + +.. code-block:: none + + **this is in bold** + +Monospace - use single backticks: + +.. code-block:: none + + the `--force` option may help + +Section headers +--------------- + +There are five section headers: + +.. code-block:: none + + # H1 + + ## H2 + + ### H3 + + #### H4 + + ##### H5 + +Inline commands +--------------- + +For commands or utilities that are mentioned in a sentence use monospace: + +.. code-block:: none + + You can type the `juju status` command to get an overview of the model. + + The `openstack` client is the preferred tool. + +Linking to an external site +--------------------------- + +.. code-block:: none + + The [OpenStack Charms Deployment Guide][cdg] ... + + . + . + + ... in the [OpenStack Charm Guide][cg] ... + + . + . + + See bug [LP #1862392][lp-bug-1862392] ... + + . + . + + + + + [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 + +Linking to a header within the current page +------------------------------------------- + +.. code-block:: none + + See section [Availability zones][anchor-az]... + + . + . + + ## Availability zones + + . + . + + + + + [anchor-az]: #availability-zones + +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: + +.. code-block:: none + + > ****: text goes here. text goes here. text goes here. text goes here + maintain the alignment. + +The text is left-aligned with the asterisks. + +Example: + +.. code-block:: none + + > **Note**: The 'ceph-rbd-mirror' charm addresses only one specific element + in datacentre redundancy. + +Code blocks +----------- + +Console input +~~~~~~~~~~~~~ + +Indent four spaces: + +.. code-block:: none + + The following command shows the relations: + + juju status --relations + +Console output +~~~~~~~~~~~~~~ + +Indent four spaces: + +.. code-block:: none + + 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: + +.. code-block:: none + + 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: + +.. code-block:: none + + The contents of file ``/etc/ec2_version`` is: + + Ubuntu 20.04.1 LTS (Focal) + +Lists +----- + +Add a blank line between each item if any list items are multi-lined. + +Unordered list +~~~~~~~~~~~~~~ + +.. code-block:: none + + * First item. Align any word-wrapped lines + like this. + + * Second item + +Nested unordered list +~~~~~~~~~~~~~~~~~~~~~ + +Indent nested items with four spaces: + +.. code-block:: none + + * First item + * Nested item + +Ordered list +~~~~~~~~~~~~ + +.. code-block:: none + + 1. First item + 1. Second item + +Nested ordered list +~~~~~~~~~~~~~~~~~~~ + +Indent nested items with four spaces: + +.. code-block:: none + + 1. First item + 1. Nested item + +Images +------ + +A regular image: + +.. code-block:: none + + ![alt-text][image] + + . + . + + + + + + [image]: path to image + +An image as hyperlink: + +.. code-block:: none + + [![alt-text][image]][image-target-link] + + . + . + + + + + + [image]: path to image + [image-target-link]: link URL diff --git a/doc/source/community/doc-contrib/rst.rst b/doc/source/community/doc-contrib/rst.rst new file mode 100644 index 00000000..32f00731 --- /dev/null +++ b/doc/source/community/doc-contrib/rst.rst @@ -0,0 +1,360 @@ +================ +reStructuredText +================ + +This page provides guidance when working with the RST format. + +General formatting +------------------ + +Italics - use single asterisks: + +.. code-block:: none + + *this is in italics* + +Bold - use double asterisks: + +.. code-block:: none + + **this is in bold** + +Monospace - use double backticks: + +.. code-block:: none + + the ``--force`` option may help + +Section headers +--------------- + +There are five section headers: + +.. code-block:: none + + ======================= + H1 (double equal signs) + ======================= + + H2 (dashes) + ----------- + + H3 (tildes) + ~~~~~~~~~~~ + + H4 (carets) + ^^^^^^^^^^^ + + H5 (dots) + ......... + +Inline commands +--------------- + +For commands or utilities that are mentioned in a sentence use the +``:command:`` directive: + +.. code-block:: none + + You can type the :command:`juju status` command to get an overview of the + model. + + The :command:`openstack` client is the preferred tool. + +Linking to an external site +--------------------------- + +.. code-block:: none + + see the `Juju documentation`_ for more details ... + + . + . + + The issue is tracked in bug `LP #1846279`_ ... + + . + . + + + .. LINKS + .. _Juju documentation: https://juju.is/docs + + .. BUGS + .. _LP #1846279: https://bugs.launchpad.net/postgresql-charm/+bug/1846279 + +Linking to a page in the doc set +-------------------------------- + +Assuming that the destination document is ``install-maas.rst`` then in the +source document: + +.. code-block:: none + + In the :doc:`previous section ` + +The linking is relative. If the destination document was in the parent +directory: + +.. code-block:: none + + In the :doc:`previous section <../install-maas>` + +Linking to a location within the current page +--------------------------------------------- + +Section headers are valid targets by default (implicit links). + +.. code-block:: none + + 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: + +.. code-block:: none + + In the example_ below + + or in `example #5`_ + + or in the :ref:`Crisis situation ` example + + . + . + + .. _example: + + . + . + + .. _example #5: + + . + . + + .. _example_crisis: + +Linking to a location within a page in the doc set +-------------------------------------------------- + +In the source document: + +.. code-block:: none + + during the :ref:`Install MAAS ` step on the previous page + +In the destination document insert the target code (typically above a section +header): + +.. code-block:: none + + .. _install_maas: + + Install MAAS + ------------ + +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: + +.. code-block:: none + + .. :: + + 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: + +.. code-block:: none + + .. note:: + + This is a note. + +Code blocks +----------- + +Syntax for code blocks: + +.. code-block:: none + + .. code-block:: + + 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 +~~~~~~~~~~~~~ + +.. code-block:: none + + The following command shows the relations: + + .. code-block:: none + + juju status --relations + +Console output +~~~~~~~~~~~~~~ + +.. code-block:: none + + 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 +~~~~~~~~~~~~ + +.. code-block:: none + + 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + + The contents of file ``/etc/ec2_version`` is: + + .. code-block:: ini + + Ubuntu 20.04.1 LTS (Focal) + +Lists +----- + +Add a blank line between each item if any list items are multi-lined. + +Unordered list +~~~~~~~~~~~~~~ + +.. code-block:: none + + * 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: + +.. code-block:: none + + * First item + + * Nested item + * Nested item + + * First item + + * Nested item + * Nested item + +Ordered list +~~~~~~~~~~~~ + +.. code-block:: none + + #. First item + #. Second item + +Nested ordered list +~~~~~~~~~~~~~~~~~~~ + +For nested lists, indent items so they align with the parent text: + +.. code-block:: none + + #. First item + + #. Nested item + #. Nested item + + #. First item + + #. Nested item + #. Nested item + +Definitions +----------- + +To define a term, indent its definition by two spaces: + +.. code-block:: none + + 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. + +Images and figures +------------------ + +To insert an image or a figure: + +.. code-block:: none + + .. image:: + : + : + +See `RST documentation on images and figures`_ for details. + +.. LINKS +.. _RST documentation on images and figures: https://docutils.sourceforge.io/docs/ref/rst/directives.html#images diff --git a/doc/source/community/doc-contrib/styleguide.rst b/doc/source/community/doc-contrib/styleguide.rst new file mode 100644 index 00000000..dd2f863d --- /dev/null +++ b/doc/source/community/doc-contrib/styleguide.rst @@ -0,0 +1,190 @@ +=================== +Writing style guide +=================== + +Overview +-------- + +This guide describes the writing style for the OpenStack Charms documentation +:ref:`sources `. + +.. note:: + + The OpenStack Charms project also abides by these guides: + + * the `OpenStack documentation contributor guide`_ + * the `Ubuntu documentation style guide`_ + + However, in cases of disagreement or ambiguity, the current document takes + precedence. + +Writing formats +--------------- + +The below pages provide specific guidance for the two writing formats used with +the OpenStack Charms project: + +.. toctree:: + :maxdepth: 1 + + rst + md + +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`_" + +.. _LP #123456: https://pad.lv/123456 +.. _GH #173: https://github.com/juju-solutions/layer-basic/issues/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: + +.. code-block:: none + + 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: + +.. code-block:: none + + 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: + +.. code-block:: none + + 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: + +.. code-block:: none + + 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: + +.. code-block:: none + + BlueStore compression is supported starting with Ceph Mimic. + +Command syntax +-------------- + +The following :command:`deploy` or :command:`add-unit` command syntax and +ordering of options should be observed: + +.. code-block:: none + + juju deploy -n --to --config ... + + juju add-unit -n --to --config ... + +Multi-line commands should have their extra lines indented by three spaces: + +.. code-block:: none + + openstack role add --user 1ea06b07c73149ca9c6753e07c30383a \ + --project Project1 Member + +.. LINKS +.. _Ubuntu documentation style guide: https://docs.ubuntu.com/styleguide/en +.. _OpenStack documentation contributor guide: https://docs.openstack.org/doc-contrib-guide +.. _Sphinx: https://www.sphinx-doc.org/en/master/index.html +.. _RST documentation on images and figures: https://docutils.sourceforge.io/docs/ref/rst/directives.html#images diff --git a/doc/source/community/software-contrib/charm-readme-template.rst b/doc/source/community/software-contrib/charm-readme-template.rst index 81fb1bc5..85eec258 100644 --- a/doc/source/community/software-contrib/charm-readme-template.rst +++ b/doc/source/community/software-contrib/charm-readme-template.rst @@ -10,8 +10,8 @@ the collection of charms. It also helps to reduce the amount of effort needed during the commit review phase (for both author and reviewer) when new charms are developed. -The writing format is Markdown. Please see the :doc:`Writing style guide -<../doc-contrib/doc-style-guide>` for the OpenStack Charms project. +The writing format is Markdown. Please see the :doc:`../doc-contrib/styleguide` +for the OpenStack Charms project. General approach ----------------