Merge pull request canonical#15 from ru-fu/cheat-sheet-v2

Cheat sheet v2

.sphinx/spellingcheck.yaml

@@ -23,3 +23,4 @@ matrix:
       - title
       - div.relatedlinks
       - div.visually-hidden
+      - img

.wordlist.txt

@@ -3,6 +3,10 @@ Permalink
 ReadMe
 roadmap
 webhook
+rST
+reStructuredText
+UI
+https
 
 accumsan
 adipiscing

doc-cheat-sheet.rst

@@ -0,0 +1,219 @@
+:orphan:
+
+.. _cheat-sheet:
+
+============================
+reStructuredText cheat sheet
+============================
+
+This file contains the syntax for commonly used rST markup.
+See the `reStructuredText style guide <https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/>`_ for detailed information and conventions.
+
+Also see the `Sphinx reStructuredText Primer <https://tinyurl.com/rstprimer>`_ for more details on rST, and the `Canonical Documentation Style Guide <https://docs.ubuntu.com/styleguide/en>`_ for general style conventions.
+
+H2 heading
+----------
+
+H3 heading
+~~~~~~~~~~
+
+H4 heading
+^^^^^^^^^^
+
+H5 heading
+..........
+
+Inline formatting
+-----------------
+
+- :guilabel:`UI element`
+- ``code``
+- :file:`file path`
+- :command:`command`
+- *Italic*
+- **Bold**
+
+Code blocks
+-----------
+
+Start a code block::
+
+     code:
+       - example: true
+
+.. code::
+
+     # Demonstrate a code block
+     code:
+       - example: true
+
+.. code:: yaml
+
+     # Demonstrate a code block
+     code:
+       - example: true
+
+.. _a_section_target:
+
+Links
+-----
+
+- `Canonical website <https://canonical.com/>`_
+- `Link defined at the bottom of the page`_
+- https:\ //canonical.com/
+- :ref:`a_section_target`
+- :ref:`Link text <a_section_target>`
+- :doc:`reference/index`
+- :doc:`Link text <reference/index>`
+
+
+Navigation
+----------
+
+Use the following syntax::
+
+  .. toctree::
+     :hidden:
+
+     sub-page1
+     sub-page2
+
+
+Lists
+-----
+
+1. Step 1
+
+   - Item 1
+
+     * Sub-item
+   - Item 2
+
+     i. Sub-step 1
+     #. Sub-step 2
+#. Step 2
+
+   a. Sub-step 1
+
+      - Item
+   #. Sub-step 2
+
+Term 1:
+  Definition
+Term 2:
+  Definition
+
+Tables
+------
+
++----------------------+------------+
+| Header 1             | Header 2   |
++======================+============+
+| Cell 1               | Cell 2     |
+|                      |            |
+| Second paragraph     |            |
++----------------------+------------+
+| Cell 3               | Cell 4     |
++----------------------+------------+
+
+.. list-table::
+   :header-rows: 1
+
+   * - Header 1
+     - Header 2
+   * - Cell 1
+
+       Second paragraph
+     - Cell 2
+   * - Cell 3
+     - Cell 4
+
+Notes
+-----
+
+.. note::
+   A note.
+
+.. tip::
+   A tip.
+
+.. important::
+   Important information
+
+.. caution::
+   This might damage your hardware!
+
+Images
+------
+
+.. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
+
+.. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
+   :width: 100px
+   :alt: Alt text
+
+   Figure caption
+
+Reuse
+-----
+
+.. |reuse_key| replace:: This is **included** text.
+
+|reuse_key|
+
+.. include:: reference/index.rst
+   :start-after: adipiscing elit.
+   :end-before: Sed tincidunt sagittis orci
+
+Tabs
+----
+
+.. tabs::
+
+   .. group-tab:: Tab 1
+
+      Content Tab 1
+
+   .. group-tab:: Tab 2
+
+      Content Tab 2
+
+
+Glossary
+--------
+
+.. glossary::
+
+   example term
+     Definition of the example term.
+
+:term:`example term`
+
+More useful markup
+------------------
+
+- .. versionadded:: X.Y
+- | Line 1
+  | Line 2
+  | Line 3
+- .. This is a comment
+- :abbr:`API (Application Programming Interface)`
+
+----
+
+Custom extensions
+-----------------
+
+Related links at the top of the page::
+
+  :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com)
+  :discourse: 12345
+
+.. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0
+          :title: Demo
+
+:spellexception:`PurposelyWrong`
+
+
+.. LINKS
+.. _Link defined at the bottom of the page: https://canonical.com/

readme.rst

@@ -1,11 +1,12 @@
 Documentation starter pack
 ==========================
 
-How to use this starter pack
-----------------------------
+See the `Sphinx and Read the Docs <https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/>`_ guide for instructions on how to get started with Sphinx documentation.
+
+Then go through the following sections to use this starter pack to set up your docs repository.
 
 Download and install
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 * *Incorporate this starter pack into an existing code repository* - copy all
   the files from this repository into your project's directory structure,
@@ -27,7 +28,7 @@ A complete set of pinned, known-working dependencies is included in
 
 
 Build and serve the documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 Start the ``sphinx-autobuild`` documentation server::
 
@@ -46,7 +47,7 @@ the more standard ``make html``.)
 
 
 Configure the documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 In ``conf.py``, you will need to check or edit several settings in the *Project information* section:
 
@@ -71,7 +72,7 @@ In the ``html_context`` variable, update the following settings:
 Save ``conf.py``.
 
 Configure the spelling check
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
 
 If your documentation uses US English instead of UK English, change this in the
 ``.sphinx/spellingcheck.yaml`` file.
@@ -82,6 +83,6 @@ file and remove all words starting from line 10.
 repository.)
 
 Configure the link check
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 If you have links in the documentation that you don't want to be checked (for example, because they are local links or give random errors even though they work), you can add them to the ``linkcheck_ignore`` variable in the ``conf.py`` file.