Merge pull request #52 from ru-fu/isolate-cheat-sheet

Isolate cheat sheet

doc-cheat-sheet-myst.md → doc-cheat-sheet-myst.md.txt

@@ -13,6 +13,8 @@ myst:
 # Markdown/MyST cheat sheet
 
 This file contains the syntax for commonly used Markdown and MyST markup.
+Open it in your text editor to quickly copy and paste the markup you need.
+
 Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information, and the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) for general style conventions.
 
 ## H2 heading
@@ -58,8 +60,8 @@ code:
 - https:/<span></span>/canonical.com/
 - {ref}`a_section_target`
 - {ref}`Link text <a_section_target>`
-- {doc}`doc-cheat-sheet`
-- {doc}`Link text <doc-cheat-sheet>`
+- {doc}`index`
+- {doc}`Link text <index>`
 
 
 ## Navigation

doc-cheat-sheet.rst → doc-cheat-sheet.rst.txt

@@ -6,9 +6,11 @@ reStructuredText cheat sheet
 ============================
 
 This file contains the syntax for commonly used reST markup.
-See the `reStructuredText style guide`_ for detailed information and conventions.
+Open it in your text editor to quickly copy and paste the markup you need.
 
-Also see the `Sphinx reStructuredText Primer`_ for more details on reST, and the `Canonical Documentation Style Guide`_ for general style conventions.
+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://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_ for more details on reST, and the `Canonical Documentation Style Guide <https://docs.ubuntu.com/styleguide/en>`_ for general style conventions.
 
 H2 heading
 ----------
@@ -59,13 +61,12 @@ Links
 -----
 
 - `Canonical website <https://canonical.com/>`_
-- `Canonical website`_ (defined in ``reuse/links.txt``)
-- `Link defined at the bottom of the page`_
+- `Canonical website`_ (defined in ``reuse/links.txt`` or at the bottom of the page)
 - https:\ //canonical.com/
 - :ref:`a_section_target`
 - :ref:`Link text <a_section_target>`
-- :doc:`doc-cheat-sheet-myst`
-- :doc:`Link text <doc-cheat-sheet-myst>`
+- :doc:`index`
+- :doc:`Link text <index>`
 
 
 Navigation
@@ -254,4 +255,4 @@ A link to a YouTube video:
 
 
 .. LINKS
-.. _Link defined at the bottom of the page: https://canonical.com/
+.. _Canonical website: https://canonical.com/

index.rst

@@ -8,13 +8,11 @@ Before you start, see the information about `Read the Docs at Canonical`_ and th
 Then, to start setting up your docs, check the :doc:`ReadMe <readme>` for instructions.
 The `Example product documentation`_ shows how to set up a Diátaxis structure in Sphinx.
 
-.. include_start
+For quick help on reST or MyST syntax, see the :file:`doc-cheat-sheet.rst.txt` or :file:`doc-cheat-sheet-myst.md.txt` files in the repository.
+(Open the files in your text editor; the rendered output is not very useful.)
 
-For quick help on reST or MyST syntax, see the :ref:`cheat-sheet` or the :ref:`cheat-sheet-myst`.
 More information is available in the `reStructuredText style guide`_.
 
-.. include_end
-
 .. toctree::
    :hidden:
    :maxdepth: 2

readme.rst

@@ -32,8 +32,9 @@ To add documentation to an existing code repository:
 #. in the above workflow file(s), set the values of the ``working-directory``
    and ``workdir`` fields to ``docs``
 #. in file ``docs/.readthedocs.yaml`` set the following:
-    * ``configuration: docs/conf.py``
-    * ``requirements: docs/.sphinx/requirements.txt``
+
+   * ``configuration: docs/conf.py``
+   * ``requirements: docs/.sphinx/requirements.txt``
 
 .. note::
 

reuse/links.txt

@@ -1,7 +1,4 @@
-.. _Canonical website: https://canonical.com/
 .. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/
-.. _Sphinx reStructuredText Primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
-.. _Canonical Documentation Style Guide: https://docs.ubuntu.com/styleguide/en
 .. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs
 .. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs
 .. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/