Add the Spinx starter pack for RTD site (ISD-2738)

.gitignore

@@ -162,3 +162,9 @@ cython_debug/
 *.charm
 *.rock
 !examples/**/lib
+
+# Docs-related files
+docs/doc-cheat-sheet-myst.md
+docs/doc-cheat-sheet.rst
+docs/.sphinx/latex_elements_template.txt
+

CHANGELOG.md

@@ -5,12 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
 ## 2024-11-29
 
 ### Changes
 
 Added a `docs` folder to hold the
 [Canonical Sphinx starter pack](https://github.com/canonical/sphinx-docs-starter-pack)
 and to eventually publish the docs on Read the Docs.
-
-## [Unreleased]

README.md

@@ -61,7 +61,8 @@ Additional resources:
 * [Tutorial to build a rock for a Flask application](https://documentation.ubuntu.com/rockcraft/en/latest/tutorial/flask/)
 * [Charmcraft `flask-framework` reference](https://juju.is/docs/sdk/charmcraft-extension-flask-framework)
 * [Charmcraft `flask-framework` how to guides](https://juju.is/docs/sdk/build-a-paas-charm)
-* [Rockcraft `flask-framework` reference](https://documentation.ubuntu.com/rockcraft/en/latest/reference/extensions/flask-framework/)
+* [Rockcraft`flask-framework`
+   reference](https://documentation.ubuntu.com/rockcraft/en/latest/reference/extensions/flask-framework/)
 
 ## Contributing
 

docs/.gitignore

@@ -14,4 +14,7 @@ __pycache__
 .vscode/
 .sphinx/styles/*
 .sphinx/vale.ini
-sp-docs/_build
+sp-docs/_build
+doc-cheat-sheet-myst.md
+doc-cheat-sheet.rst
+.sphinx/latex_elements_template.txt

docs/.readthedocs.yaml

@@ -10,9 +10,9 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.11"
+    python: "3.13"
   jobs:
     pre_install:
       - git fetch --unshallow || true

docs/.sphinx/.markdownlint.json

@@ -1,7 +1,7 @@
 {
     "default": false,
     "MD003": { "style": "atx" },
-    "MD013": { "code_blocks": false, "tables": false, "stern": true, "line_length": 150},
+    "MD013": { "code_blocks": false, "tables": false, "stern": true, "line_length": 120},
     "MD014": true,
     "MD018": true,
     "MD022": true,
@@ -13,4 +13,4 @@
     "MD042": true,
     "MD045": true,
     "MD052": true
-}
+}

docs/.sphinx/latex_elements_template.txt

@@ -3,9 +3,9 @@
     'pointsize': '11pt',
     'fncychap': '',
     'preamble': r'''
-%\usepackage{charter}
-%\usepackage[defaultsans]{lato}
-%\usepackage{inconsolata}
+% \usepackage{charter}
+% \usepackage[defaultsans]{lato}
+% \usepackage{inconsolata}
 \setmainfont[UprightFont = *-R, BoldFont = *-B, ItalicFont=*-RI, Extension = .ttf]{Ubuntu}
 \setmonofont[UprightFont = *-R, BoldFont = *-B, ItalicFont=*-RI, Extension = .ttf]{UbuntuMono}
 \usepackage[most]{tcolorbox}
@@ -116,4 +116,4 @@
       \end{tikzpicture}
     }
 ''',
-}
+}

docs/.sphinx/spellingcheck.yaml

@@ -5,7 +5,7 @@ matrix:
   - name: rST files
     aspell:
       lang: en
-      d: en_GB
+      d: en_US
     dictionary:
       wordlists:
         - .sphinx/.wordlist.txt

docs/doc-cheat-sheet-myst.md

@@ -0,0 +1,273 @@
+---
+orphan: true
+myst:
+    substitutions:
+      reuse_key: "This is **included** text."
+      advanced_reuse_key: "This is a substitution that includes a code block:
+                         ```
+                         code block
+                         ```"
+---
+
+<!-- vale off -->
+
+(cheat-sheet-myst)=
+# Markdown/MyST cheat sheet
+
+<!-- vale on -->
+
+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.
+
+See the [MyST style guide](https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/) for detailed information and conventions.
+
+Also see the [MyST documentation](https://myst-parser.readthedocs.io/en/latest/index.html) for detailed information on MyST, and the [Canonical Documentation Style Guide](https://docs.ubuntu.com/styleguide/en) for general style conventions.
+
+## H2 heading
+
+Content.
+
+### H3 heading
+
+Content.
+
+#### H4 heading
+
+Content.
+
+##### H5 heading
+
+Content.
+
+## Inline formatting
+
+- {guilabel}`UI element`
+- `code`
+- {command}`command`
+- {kbd}`Key`
+- *Italic*
+- **Bold**
+
+## Code blocks
+
+Start a code block:
+
+    code:
+      - example: true
+
+Demonstrate a code block:
+
+```
+code:
+  - example: true
+```
+
+Demonstrate a code block (yaml):
+
+```yaml
+code:
+  - example: true
+```
+
+(a_section_target_myst)=
+## Links
+
+- [Canonical website](https://canonical.com/)
+- {ref}`a_section_target_myst`
+- {ref}`Link text <a_section_target_myst>`
+- {doc}`index`
+- {doc}`Link text <index>`
+
+## Navigation
+
+Use the following syntax::
+
+    ```{toctree}
+    :hidden:
+
+    sub-page1
+    sub-page2
+    ```
+
+## Lists
+
+1. Step 1
+   - Item 1
+      * Sub-item
+   - Item 2
+     1. Sub-step 1
+     1. Sub-step 2
+1. Step 2
+   1. Sub-step 1
+      - Item
+   1. Sub-step 2
+
+Term 1
+: Definition
+
+Term 2
+: Definition
+
+## Tables
+
+Demonstrate different kinds of tables.
+
+## Markdown tables
+
+| Header 1                           | Header 2 |
+|------------------------------------|----------|
+| Cell 1<br>Second paragraph         | Cell 2   |
+| Cell 3                             | Cell 4   |
+
+Centred:
+
+| Header 1                           | Header 2 |
+|:----------------------------------:|:--------:|
+| Cell 1<br>Second paragraph         | Cell 2   |
+| Cell 3                             | Cell 4   |
+
+## List tables
+
+```{list-table}
+   :header-rows: 1
+
+* - Header 1
+  - Header 2
+* - Cell 1
+
+    Second paragraph
+  - Cell 2
+* - Cell 3
+  - Cell 4
+```
+
+Centred:
+
+```{list-table}
+   :header-rows: 1
+   :align: center
+
+* - 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
+
+![Alt text](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
+
+### Keys
+
+Keys can be defined at the top of a file, or in a `myst_substitutions` option in `conf.py`.
+
+{{reuse_key}}
+
+{{advanced_reuse_key}}
+
+### File inclusion
+
+```{include} index.md
+   :start-after: include_start
+   :end-before: include_end
+```
+
+## Tabs
+
+````{tabs}
+```{group-tab} Tab 1
+
+Content Tab 1
+```
+
+```{group-tab} Tab 2
+Content Tab 2
+```
+````
+
+## Glossary
+
+```{glossary}
+
+some term
+  Definition of the example term.
+```
+
+{term}`some term`
+
+## More useful markup
+
+- ```{versionadded} X.Y
+- {abbr}`API (Application Programming Interface)`
+
+----
+
+## Custom extensions
+
+Related links at the top of the page (surrounded by `---`):
+
+    relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com)
+    discourse: 12345
+
+Terms that should not be checked by the spelling checker: {spellexception}`PurposelyWrong`
+
+A single-line terminal view that separates input from output:
+
+```{terminal}
+   :input: command
+   :user: root
+   :host: vampyr
+   :dir: /home/user/directory/
+
+the output
+```
+
+A multi-line version of the same:
+
+```{terminal}
+   :user: root
+   :host: vampyr
+   :dir: /home/user/directory/
+
+:input: command 1
+output 1
+:input: command 2
+output 2
+```
+
+A link to a YouTube video:
+
+```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0
+   :title: Demo
+```

docs/doc-cheat-sheet.rst

@@ -52,15 +52,17 @@ Start a code block::
      code:
        - example: true
 
+Demonstrate a code block:
+
 .. code::
 
-     # Demonstrate a code block
      code:
        - example: true
 
+Demonstrate a code block (yaml):
+
 .. code:: yaml
 
-     # Demonstrate a code block
      code:
        - example: true