├── .sphinx
    ├── _static
    │   ├── tag.png
    │   ├── favicon.png
    │   ├── header-nav.js
    │   ├── github_issue_links.css
    │   ├── github_issue_links.js
    │   ├── header.css
    │   └── custom.css
    ├── _templates
    │   ├── base.html
    │   ├── header.html
    │   ├── page.html
    │   └── footer.html
    ├── requirements.txt
    ├── spellingcheck.yaml
    └── pinned-requirements.txt
├── .gitignore
├── .wordlist.txt
├── .wokeignore
├── reuse
    └── links.txt
├── .readthedocs.yaml
├── index.rst
├── make.bat
├── .github
    └── workflows
    │   └── automatic-doc-checks.yml
├── Makefile
├── custom_conf.py
├── doc-cheat-sheet-myst.md
├── doc-cheat-sheet.rst
├── conf.py
└── readme.rst


/.sphinx/_static/tag.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/canonical/alpha-docs/main/.sphinx/_static/tag.png


--------------------------------------------------------------------------------
/.sphinx/_static/favicon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/canonical/alpha-docs/main/.sphinx/_static/favicon.png


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | /*env*/
2 | .sphinx/venv
3 | .sphinx/warnings.txt
4 | .sphinx/.wordlist.dic
5 | _build
6 | .DS_Store
7 | __pycache__
8 | .idea/
9 | 


--------------------------------------------------------------------------------
/.sphinx/_templates/base.html:
--------------------------------------------------------------------------------
1 | {% extends "furo/base.html" %}
2 | 
3 | {% block theme_scripts %}
4 | <script>
5 |   const github_url = "{{ github_url }}";
6 | </script>
7 | {% endblock theme_scripts %}
8 | 


--------------------------------------------------------------------------------
/.wordlist.txt:
--------------------------------------------------------------------------------
 1 | Permalink
 2 | ReadMe
 3 | reST
 4 | reStructuredText
 5 | UI
 6 | https
 7 | MyST
 8 | favicon
 9 | installable
10 | Makefile
11 | Diátaxis
12 | RTD
13 | yaml
14 | readthedocs
15 | txt
16 | 


--------------------------------------------------------------------------------
/.wokeignore:
--------------------------------------------------------------------------------
1 | # the cheat sheets contain a link to a link with a block word which we cannot
2 | # avoid for now, ie
3 | # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
4 | doc-cheat-sheet*
5 | 


--------------------------------------------------------------------------------
/.sphinx/requirements.txt:
--------------------------------------------------------------------------------
 1 | sphinx
 2 | sphinx-autobuild
 3 | sphinx-design
 4 | furo
 5 | sphinx-tabs
 6 | sphinx-reredirects
 7 | pyspelling
 8 | sphinxext-opengraph
 9 | lxd-sphinx-extensions
10 | sphinx-copybutton
11 | myst-parser
12 | sphinxcontrib-jquery
13 | 


--------------------------------------------------------------------------------
/.sphinx/_static/header-nav.js:
--------------------------------------------------------------------------------
 1 | $(document).ready(function() {
 2 |     $(document).on("click", function () {
 3 |         $(".more-links-dropdown").hide();
 4 |     });
 5 | 
 6 |     $('.nav-more-links').click(function(event) {
 7 |         $('.more-links-dropdown').toggle();
 8 |         event.stopPropagation();
 9 |     });
10 | })
11 | 


--------------------------------------------------------------------------------
/reuse/links.txt:
--------------------------------------------------------------------------------
1 | .. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/
2 | .. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs
3 | .. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs
4 | .. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/
5 | 


--------------------------------------------------------------------------------
/.sphinx/spellingcheck.yaml:
--------------------------------------------------------------------------------
 1 | matrix:
 2 | - name: rST files
 3 |   aspell:
 4 |     lang: en
 5 |     d: en_GB
 6 |   dictionary:
 7 |     wordlists:
 8 |     - .wordlist.txt
 9 |     output: .sphinx/.wordlist.dic
10 |   sources:
11 |   - _build/**/*.html
12 |   pipeline:
13 |   - pyspelling.filters.html:
14 |       comments: false
15 |       attributes:
16 |       - title
17 |       - alt
18 |       ignores:
19 |       - code
20 |       - pre
21 |       - spellexception
22 |       - link
23 |       - title
24 |       - div.relatedlinks
25 |       - div.visually-hidden
26 |       - img
27 |       - a.p-navigation__link
28 | 


--------------------------------------------------------------------------------
/.sphinx/_static/github_issue_links.css:
--------------------------------------------------------------------------------
 1 | .github-issue-link-container {
 2 |     padding-right: 0.5rem;
 3 | }
 4 | .github-issue-link {
 5 |     font-size: var(--font-size--small);
 6 |     font-weight: bold;
 7 |     background-color: #DD4814;
 8 |     padding: 13px 23px;
 9 |     text-decoration: none;
10 | }
11 | .github-issue-link:link {
12 |     color: #FFFFFF;
13 | }
14 | .github-issue-link:visited {
15 |     color: #FFFFFF
16 | }
17 | .muted-link.github-issue-link:hover {
18 |     color: #FFFFFF;
19 |     text-decoration: underline;
20 | }
21 | .github-issue-link:active {
22 |     color: #FFFFFF;
23 |     text-decoration: underline;
24 | }
25 | 


--------------------------------------------------------------------------------
/.readthedocs.yaml:
--------------------------------------------------------------------------------
 1 | # .readthedocs.yaml
 2 | # Read the Docs configuration file
 3 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 4 | 
 5 | # Required
 6 | version: 2
 7 | 
 8 | # Set the version of Python and other tools you might need
 9 | build:
10 |   os: ubuntu-22.04
11 |   tools:
12 |     python: "3.11"
13 | 
14 | # Build documentation in the docs/ directory with Sphinx
15 | sphinx:
16 |   builder: dirhtml
17 |   configuration: conf.py
18 |   fail_on_warning: true
19 | 
20 | # If using Sphinx, optionally build your docs in additional formats such as PDF
21 | formats:
22 |    - pdf
23 | 
24 | # Optionally declare the Python requirements required to build your docs
25 | python:
26 |    install:
27 |    - requirements: .sphinx/requirements.txt
28 | 


--------------------------------------------------------------------------------
/index.rst:
--------------------------------------------------------------------------------
 1 | Starter pack
 2 | ============
 3 | 
 4 | This starter pack contains the files you need to quickly set up your Sphinx documentation.
 5 | 
 6 | Before you start, see the information about `Read the Docs at Canonical`_ and the instructions for `How to publish documentation on Read the Docs`_.
 7 | 
 8 | Then, to start setting up your docs, check the :doc:`ReadMe <readme>` for instructions.
 9 | The `Example product documentation`_ shows how to set up a Diátaxis structure in Sphinx.
10 | 
11 | 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.
12 | (Open the files in your text editor; the rendered output is not very useful.)
13 | 
14 | More information is available in the `reStructuredText style guide`_.
15 | 
16 | .. toctree::
17 |    :hidden:
18 |    :maxdepth: 2
19 | 
20 |    ReadMe <readme>
21 | 


--------------------------------------------------------------------------------
/.sphinx/_static/github_issue_links.js:
--------------------------------------------------------------------------------
 1 | window.onload = function() {
 2 |     const link = document.createElement("a");
 3 |     link.classList.add("muted-link");
 4 |     link.classList.add("github-issue-link");
 5 |     link.text = "Give feedback";
 6 |     link.href = (
 7 |         github_url
 8 |         + "/issues/new?"
 9 |         + "title=docs%3A+TYPE+YOUR+QUESTION+HERE"
10 |         + "&body=*Please describe the question or issue you're facing with "
11 |         + `"${document.title}"`
12 |         + ".*"
13 |         + "%0A%0A%0A%0A%0A"
14 |         + "---"
15 |         + "%0A"
16 |         + `*Reported+from%3A+${location.href}*`
17 |     );
18 |     link.target = "_blank";
19 | 
20 |     const div = document.createElement("div");
21 |     div.classList.add("github-issue-link-container");
22 |     div.append(link)
23 | 
24 |     const container = document.querySelector(".article-container > .content-icon-container");
25 |     container.prepend(div);
26 | };
27 | 


--------------------------------------------------------------------------------
/make.bat:
--------------------------------------------------------------------------------
 1 | @ECHO OFF
 2 | 
 3 | pushd %~dp0
 4 | 
 5 | REM Command file for Sphinx documentation
 6 | 
 7 | if "%SPHINXBUILD%" == "" (
 8 | 	set SPHINXBUILD=sphinx-build
 9 | )
10 | set SOURCEDIR=.
11 | set BUILDDIR=_build
12 | 
13 | %SPHINXBUILD% >NUL 2>NUL
14 | if errorlevel 9009 (
15 | 	echo.
16 | 	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17 | 	echo.installed, then set the SPHINXBUILD environment variable to point
18 | 	echo.to the full path of the 'sphinx-build' executable. Alternatively you
19 | 	echo.may add the Sphinx directory to PATH.
20 | 	echo.
21 | 	echo.If you don't have Sphinx installed, grab it from
22 | 	echo.https://www.sphinx-doc.org/
23 | 	exit /b 1
24 | )
25 | 
26 | if "%1" == "" goto help
27 | 
28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29 | goto end
30 | 
31 | :help
32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33 | 
34 | :end
35 | popd
36 | 


--------------------------------------------------------------------------------
/.sphinx/_templates/header.html:
--------------------------------------------------------------------------------
 1 | <header id="header" class="p-navigation">
 2 | 
 3 |   <div class="p-navigation__nav" role="menubar">
 4 | 
 5 |     <ul class="p-navigation__links" role="menu">
 6 | 
 7 |       <li>
 8 |         <a class="p-logo" href="https://{{ product_page }}" aria-current="page">
 9 |           <img src="{{ pathto(product_tag,1) }}" alt="Logo" class="p-logo-image">
10 |           <div class="p-logo-text p-heading--4">{{ project }}
11 |           </div>
12 |         </a>
13 |       </li>
14 | 
15 |       <li class="nav-ubuntu-com">
16 |         <a href="https://{{ product_page }}" class="p-navigation__link">{{ product_page }}</a>
17 |       </li>
18 | 
19 |       <li>
20 |         <a href="#" class="p-navigation__link nav-more-links">More resources</a>
21 |         <ul class="more-links-dropdown">
22 | 
23 |           <li>
24 |             <a href="{{ discourse }}" class="p-navigation__sub-link p-dropdown__link">Forum</a>
25 |           </li>
26 | 
27 |           <li>
28 |             <a href="{{ github_url }}" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
29 |           </li>
30 | 
31 |         </ul>
32 |       </li>
33 | 
34 |     </ul>
35 |   </div>
36 | </header>
37 | 


--------------------------------------------------------------------------------
/.sphinx/pinned-requirements.txt:
--------------------------------------------------------------------------------
 1 | alabaster==0.7.13
 2 | Babel==2.12.1
 3 | beautifulsoup4==4.11.2
 4 | bracex==2.3.post1
 5 | certifi==2022.12.7
 6 | charset-normalizer==3.1.0
 7 | colorama==0.4.6
 8 | contourpy==1.0.7
 9 | cycler==0.11.0
10 | docutils==0.19
11 | fonttools==4.39.0
12 | furo==2022.12.7
13 | html5lib==1.1
14 | idna==3.4
15 | imagesize==1.4.1
16 | importlib-metadata==6.0.0
17 | importlib-resources==5.12.0
18 | Jinja2==3.1.2
19 | kiwisolver==1.4.4
20 | livereload==2.6.3
21 | lxd-sphinx-extensions==0.0.6
22 | lxml==4.9.2
23 | Markdown==3.4.1
24 | MarkupSafe==2.1.2
25 | matplotlib==3.7.1
26 | numpy==1.24.2
27 | packaging==23.0
28 | Pillow==9.4.0
29 | Pygments==2.14.0
30 | pyparsing==3.0.9
31 | pyspelling==2.8.2
32 | python-dateutil==2.8.2
33 | pytz==2022.7.1
34 | PyYAML==6.0
35 | requests==2.28.2
36 | six==1.16.0
37 | snowballstemmer==2.2.0
38 | soupsieve==2.4
39 | sphinx==6.1.3
40 | sphinx-autobuild==2021.3.14
41 | sphinx-basic-ng==1.0.0b1
42 | sphinx-copybutton==0.5.1
43 | sphinx-design==0.3.0
44 | sphinx-reredirects==0.1.1
45 | sphinx-tabs==3.4.1
46 | sphinxcontrib-applehelp==1.0.4
47 | sphinxcontrib-devhelp==1.0.2
48 | sphinxcontrib-htmlhelp==2.0.1
49 | sphinxcontrib-jsmath==1.0.1
50 | sphinxcontrib-qthelp==1.0.3
51 | sphinxcontrib-serializinghtml==1.1.5
52 | sphinxext-opengraph==0.8.1
53 | tornado==6.2
54 | urllib3==1.26.14
55 | wcmatch==8.4.1
56 | webencodings==0.5.1
57 | zipp==3.15.0
58 | 


--------------------------------------------------------------------------------
/.sphinx/_templates/page.html:
--------------------------------------------------------------------------------
 1 | {% extends "furo/page.html" %}
 2 | 
 3 | {% block footer %}
 4 |    {% include "footer.html" %}
 5 | {% endblock footer %}
 6 | 
 7 | {% block body -%}
 8 |    {% include "header.html" %}
 9 |    {{ super() }}
10 | {%- endblock body %}
11 | 
12 | {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
13 |    {% set furo_hide_toc_orig = furo_hide_toc %}
14 |    {% set furo_hide_toc=false %}
15 | {% endif %}
16 | 
17 | {% block right_sidebar %}
18 | <div class="toc-sticky toc-scroll">
19 |    {% if not furo_hide_toc_orig %}
20 |     <div class="toc-title-container">
21 |       <span class="toc-title">
22 |        {{ _("Contents") }}
23 |       </span>
24 |     </div>
25 |     <div class="toc-tree-container">
26 |       <div class="toc-tree">
27 |         {{ toc }}
28 |       </div>
29 |     </div>
30 |    {% endif %}
31 |     {% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
32 |     <div class="relatedlinks-title-container">
33 |       <span class="relatedlinks-title">
34 |        Related links
35 |       </span>
36 |     </div>
37 |     <div class="relatedlinks-container">
38 |       <div class="relatedlinks">
39 |         {% if meta.discourse and discourse_prefix %}
40 |           {{ discourse_links(meta.discourse) }}
41 |         {% endif %}
42 |         {% if meta.relatedlinks %}
43 |           {{ related_links(meta.relatedlinks) }}
44 |         {% endif %}
45 |       </div>
46 |     </div>
47 |     {% endif %}
48 |   </div>
49 | {% endblock right_sidebar %}
50 | 


--------------------------------------------------------------------------------
/.github/workflows/automatic-doc-checks.yml:
--------------------------------------------------------------------------------
 1 | name: Automatic documentation checks
 2 | 
 3 | on:
 4 |   - push
 5 |   - pull_request
 6 | 
 7 | concurrency:
 8 |   group: ${{ github.workflow }}-${{ github.ref }}
 9 |   cancel-in-progress: true
10 | 
11 | jobs:
12 |   spellcheck:
13 |     name: Spelling check
14 |     runs-on: ubuntu-latest
15 |     steps:
16 |       - name: Checkout
17 |         uses: actions/checkout@v3
18 | 
19 |       - name: Install Aspell
20 |         run: |
21 |           sudo apt-get install aspell aspell-en
22 | 
23 |       - name: Install the doc framework
24 |         working-directory: .
25 |         run: |
26 |           make install
27 | 
28 |       - name: Build docs and run spelling checker
29 |         working-directory: .
30 |         run: |
31 |           make spelling
32 | 
33 |   woke:
34 |     name: Inclusive language check
35 |     runs-on: ubuntu-latest
36 |     steps:
37 |       - name: Checkout
38 |         uses: actions/checkout@v3
39 | 
40 |       - name: woke
41 |         uses: get-woke/woke-action@v0
42 |         with:
43 |           # Cause the check to fail on any broke rules
44 |           fail-on-error: true
45 |           workdir: .
46 |           woke-args: "*.rst **/*.rst -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml"
47 | 
48 |   linkcheck:
49 |     name: Link check
50 |     runs-on: ubuntu-latest
51 |     steps:
52 |       - name: Checkout
53 |         uses: actions/checkout@v3
54 | 
55 |       - name: Install the doc framework
56 |         working-directory: .
57 |         run: |
58 |           make install
59 | 
60 |       - name: Run linkchecker
61 |         working-directory: .
62 |         run: |
63 |           make linkcheck
64 | 


--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
 1 | # Minimal makefile for Sphinx documentation
 2 | #
 3 | 
 4 | # You can set these variables from the command line, and also
 5 | # from the environment for the first two.
 6 | SPHINXOPTS    ?=
 7 | SPHINXBUILD   ?= sphinx-build
 8 | SOURCEDIR     = .
 9 | BUILDDIR      = _build
10 | VENV          = .sphinx/venv/bin/activate
11 | 
12 | 
13 | # Put it first so that "make" without argument is like "make help".
14 | help:
15 | 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
16 | 
17 | install:
18 | 	@echo "... setting up virtualenv"
19 | 	python3 -m venv .sphinx/venv
20 | 	. $(VENV); pip install --upgrade -r .sphinx/requirements.txt
21 | 
22 | 	@echo "\n" \
23 | 		"--------------------------------------------------------------- \n" \
24 | 		"* watch, build and serve the documentation: make run \n" \
25 |                 "* only build: make html \n" \
26 |                 "* only serve: make serve \n" \
27 |                 "* clean built doc files: make clean-doc \n" \
28 |                 "* clean full environment: make clean \n" \
29 | 		"* check spelling: make spelling \n" \
30 |                 "* check inclusive language: make woke \n" \
31 | 		"--------------------------------------------------------------- \n"
32 | run:
33 | 	. $(VENV); sphinx-autobuild -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)"
34 | 
35 | html:
36 | 	. $(VENV); $(SPHINXBUILD) -c . -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt
37 | 
38 | epub:
39 | 	. $(VENV); $(SPHINXBUILD) -c . -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w .sphinx/warnings.txt
40 | 
41 | serve:
42 | 	cd "$(BUILDDIR)"; python3 -m http.server 8000
43 | 
44 | clean: clean-doc
45 | 	rm -rf .sphinx/venv
46 | 
47 | clean-doc:
48 | 	git clean -fx "$(BUILDDIR)"
49 | 
50 | spelling: html
51 | 	. $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml
52 | 
53 | linkcheck:
54 | 	. $(VENV) ; $(SPHINXBUILD) -c . -b linkcheck  "$(SOURCEDIR)" "$(BUILDDIR)"
55 | 
56 | woke:
57 | 	type woke >/dev/null 2>&1 || { snap install woke; exit 1; }
58 | 	woke *.rst **/*.rst -c https://github.com/canonical-web-and-design/Inclusive-naming/raw/main/config.yml
59 | 
60 | .PHONY: help Makefile
61 | 
62 | # Catch-all target: route all unknown targets to Sphinx using the new
63 | # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
64 | %: Makefile
65 | 	. $(VENV); $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
66 | 


--------------------------------------------------------------------------------
/.sphinx/_templates/footer.html:
--------------------------------------------------------------------------------
 1 | {# ru-fu: copied from Furo, with modifications as stated below #}
 2 | 
 3 | <div class="related-pages">
 4 |   {% if next -%}
 5 |     <a class="next-page" href="{{ next.link }}">
 6 |       <div class="page-info">
 7 |         <div class="context">
 8 |           <span>{{ _("Next") }}</span>
 9 |         </div>
10 |         <div class="title">{{ next.title }}</div>
11 |       </div>
12 |       <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
13 |     </a>
14 |   {%- endif %}
15 |   {% if prev -%}
16 |     <a class="prev-page" href="{{ prev.link }}">
17 |       <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
18 |       <div class="page-info">
19 |         <div class="context">
20 |           <span>{{ _("Previous") }}</span>
21 |         </div>
22 |         {% if prev.link == pathto(master_doc) %}
23 |         <div class="title">{{ _("Home") }}</div>
24 |         {% else %}
25 |         <div class="title">{{ prev.title }}</div>
26 |         {% endif %}
27 |       </div>
28 |     </a>
29 |   {%- endif %}
30 | </div>
31 | <div class="bottom-of-page">
32 |   <div class="left-details">
33 |     {%- if show_copyright %}
34 |     <div class="copyright">
35 |       {%- if hasdoc('copyright') %}
36 |         {% trans path=pathto('copyright'), copyright=copyright|e -%}
37 |           <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
38 |         {%- endtrans %}
39 |       {%- else %}
40 |         {% trans copyright=copyright|e -%}
41 |           Copyright &#169; {{ copyright }}
42 |         {%- endtrans %}
43 |       {%- endif %}
44 |     </div>
45 |     {%- endif %}
46 | 
47 |     {# ru-fu: removed "Made with" #}
48 | 
49 |     {%- if last_updated -%}
50 |     <div class="last-updated">
51 |       {% trans last_updated=last_updated|e -%}
52 |         Last updated on {{ last_updated }}
53 |       {%- endtrans -%}
54 |     </div>
55 |     {%- endif %}
56 | 
57 |     {%- if show_source and has_source and sourcename %}
58 |     <div class="show-source">
59 |       <a class="muted-link" href="{{ pathto('_sources/' + sourcename, true)|e }}"
60 |          rel="nofollow">Show source</a>
61 |     </div>
62 |     {%- endif %}
63 |   </div>
64 |   <div class="right-details">
65 | 
66 |     {# ru-fu: replaced RTD icons with our links #}
67 | 
68 |     {% if discourse %}
69 |     <div class="ask-discourse">
70 |       <a class="muted-link" href="{{ discourse }}">Ask a question on Discourse</a>
71 |     </div>
72 |     {% endif %}
73 | 
74 |     {% if github_url and github_version and github_folder %}
75 | 
76 |     {% if github_issues %}
77 |     <div class="issue-github">
78 |       <a class="muted-link" href="{{ github_url }}/issues/new?title=doc%3A+ADD+A+TITLE&body=DESCRIBE+THE+ISSUE%0A%0A---%0ADocument: {{ pagename }}{{ page_source_suffix }}">Open a GitHub issue for this page</a>
79 |     </div>
80 |     {% endif %}
81 | 
82 |     <div class="edit-github">
83 |       <a class="muted-link" href="{{ github_url }}/edit/{{ github_version }}{{ github_folder }}{{ pagename }}{{ page_source_suffix }}">Edit this page on GitHub</a>
84 |     </div>
85 |     {% endif %}
86 | 
87 | 
88 |     </div>
89 |   </div>
90 | </div>
91 | 


--------------------------------------------------------------------------------
/.sphinx/_static/header.css:
--------------------------------------------------------------------------------
  1 | .p-navigation {
  2 |   border-bottom: 1px solid var(--color-sidebar-background-border);
  3 | }
  4 | 
  5 | .p-navigation__nav {
  6 |   background: #333333;
  7 |   display: flex;
  8 | }
  9 | 
 10 | .p-logo {
 11 |   display: flex !important;
 12 |   padding-top: 0 !important;
 13 |   text-decoration: none;
 14 | }
 15 | 
 16 | .p-logo-image {
 17 |   height: 44px;
 18 |   padding-right: 10px;
 19 | }
 20 | 
 21 | .p-logo-text {
 22 |   margin-top: 18px;
 23 |   color: white;
 24 |   text-decoration: none;
 25 | }
 26 | 
 27 | ul.p-navigation__links {
 28 |   display: flex;
 29 |   list-style: none;
 30 |   margin-left: 0;
 31 |   margin-top: auto;
 32 |   margin-bottom: auto;
 33 |   max-width: 800px;
 34 |   width: 100%;
 35 | }
 36 | 
 37 | ul.p-navigation__links li {
 38 |   margin: 0 auto;
 39 |   text-align: center;
 40 |   width: 100%;
 41 | }
 42 | 
 43 | ul.p-navigation__links li a {
 44 |   background-color: rgba(0, 0, 0, 0);
 45 |   border: none;
 46 |   border-radius: 0;
 47 |   color: var(--color-sidebar-link-text);
 48 |   display: block;
 49 |   font-weight: 400;
 50 |   line-height: 1.5rem;
 51 |   margin: 0;
 52 |   overflow: hidden;
 53 |   padding: 1rem 0;
 54 |   position: relative;
 55 |   text-align: left;
 56 |   text-overflow: ellipsis;
 57 |   transition-duration: .1s;
 58 |   transition-property: background-color, color, opacity;
 59 |   transition-timing-function: cubic-bezier(0.215, 0.61, 0.355, 1);
 60 |   white-space: nowrap;
 61 |   width: 100%;
 62 | }
 63 | 
 64 | ul.p-navigation__links .p-navigation__link {
 65 |   color: #ffffff;
 66 |   font-weight: 300;
 67 |   text-align: center;
 68 |   text-decoration: none;
 69 | }
 70 | 
 71 | ul.p-navigation__links .p-navigation__link:hover {
 72 |   background-color: #2b2b2b;
 73 | }
 74 | 
 75 | ul.p-navigation__links .p-dropdown__link:hover {
 76 |   background-color: var(--color-sidebar-item-background--hover);
 77 | }
 78 | 
 79 | ul.p-navigation__links .p-navigation__sub-link {
 80 |   background: var(--color-background-primary);
 81 |   padding: .5rem 0 .5rem .5rem;
 82 |   font-weight: 300;
 83 | }
 84 | 
 85 | ul.p-navigation__links .more-links-dropdown li a {
 86 |   border-left: 1px solid var(--color-sidebar-background-border);
 87 |   border-right: 1px solid var(--color-sidebar-background-border);
 88 | }
 89 | 
 90 | ul.p-navigation__links .more-links-dropdown li:first-child a {
 91 |   border-top: 1px solid var(--color-sidebar-background-border);
 92 | }
 93 | 
 94 | ul.p-navigation__links .more-links-dropdown li:last-child a {
 95 |   border-bottom: 1px solid var(--color-sidebar-background-border);
 96 | }
 97 | 
 98 | ul.p-navigation__links .p-navigation__logo {
 99 |   padding: 0.5rem;
100 | }
101 | 
102 | ul.p-navigation__links .p-navigation__logo img {
103 |   width: 40px;
104 | }
105 | 
106 | ul.more-links-dropdown {
107 |   display: none;
108 |   overflow-x: visible;
109 |   height: 0;
110 |   z-index: 55;
111 |   padding: 0;
112 |   position: relative;
113 |   list-style: none;
114 |   margin-bottom: 0;
115 |   margin-top: 0;
116 | }
117 | 
118 | .nav-more-links::after {
119 |   background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath fill='%23111' d='M8.187 11.748l6.187-6.187-1.06-1.061-5.127 5.127L3.061 4.5 2 5.561z'/%3E%3C/svg%3E");
120 |   background-position: center;
121 |   background-repeat: no-repeat;
122 |   background-size: contain;
123 |   content: "";
124 |   display: block;
125 |   filter: invert(100%);
126 |   height: 1rem;
127 |   pointer-events: none;
128 |   position: absolute;
129 |   right: 1rem;
130 |   text-indent: calc(100% + 10rem);
131 |   top: calc(1rem + 0.25rem);
132 |   width: 1rem;
133 | }
134 | 
135 | .nav-ubuntu-com {
136 |   display: none;
137 | }
138 | 
139 | @media only screen and (min-width: 480px) {
140 |   ul.p-navigation__links li {
141 |     width: 100%;
142 |   }
143 | 
144 |   .nav-ubuntu-com {
145 |     display: inherit;
146 |   }
147 | }
148 | 
149 | @media only screen and (max-width: 800px) {
150 |   .nav-more-links {
151 |     margin-left: auto !important;
152 |     padding-right: 2rem !important;
153 |     width: 8rem !important;
154 |   }
155 | }
156 | 
157 | @media only screen and (min-width: 800px) {
158 |   ul.p-navigation__links li {
159 |     width: 100% !important;
160 |   }
161 | }
162 | 
163 | @media only screen and (min-width: 1310px) {
164 |   ul.p-navigation__links {
165 |     margin-left: calc(50% - 41em);
166 |   }
167 | }
168 | 


--------------------------------------------------------------------------------
/custom_conf.py:
--------------------------------------------------------------------------------
  1 | import datetime
  2 | 
  3 | # Custom configuration for the Sphinx documentation builder.
  4 | # All configuration specific to your project should be done in this file.
  5 | #
  6 | # The file is included in the common conf.py configuration file.
  7 | # You can modify any of the settings below or add any configuration that
  8 | # is not covered by the common conf.py file.
  9 | #
 10 | # For the full list of built-in configuration values, see the documentation:
 11 | # https://www.sphinx-doc.org/en/master/usage/configuration.html
 12 | 
 13 | ############################################################
 14 | ### Project information
 15 | ############################################################
 16 | 
 17 | # Product name
 18 | project = 'Documentation starter pack'
 19 | author = 'Canonical Group Ltd'
 20 | 
 21 | # Uncomment if your product uses release numbers
 22 | # release = '1.0'
 23 | 
 24 | # The default value uses the current year as the copyright year
 25 | copyright = '%s, %s' % (datetime.date.today().year, author)
 26 | 
 27 | ## Open Graph configuration - defines what is displayed in the website preview
 28 | # The URL of the documentation output
 29 | ogp_site_url = 'https://canonical-starter-pack.readthedocs-hosted.com/'
 30 | # The documentation website name (usually the same as the product name)
 31 | ogp_site_name = project
 32 | # An image or logo that is used in the preview
 33 | ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
 34 | 
 35 | # Update with the favicon for your product (default is the circle of friends)
 36 | html_favicon = '.sphinx/_static/favicon.png'
 37 | 
 38 | # (Some settings must be part of the html_context dictionary, while others
 39 | #  are on root level. Don't move the settings.)
 40 | html_context = {
 41 | 
 42 |     # Change to the link to your product website (without "https://")
 43 |     'product_page': 'documentation.ubuntu.com',
 44 | 
 45 |     # Add your product tag to ".sphinx/_static" and change the path
 46 |     # here (start with "_static"), default is the circle of friends
 47 |     'product_tag': '_static/tag.png',
 48 | 
 49 |     # Change to the discourse instance you want to be able to link to
 50 |     # using the :discourse: metadata at the top of a file
 51 |     # (use an empty value if you don't want to link)
 52 |     'discourse': 'https://discourse.ubuntu.com',
 53 | 
 54 |     # Change to the GitHub info for your project
 55 |     'github_url': 'https://github.com/canonical/starter-pack',
 56 | 
 57 |     # Change to the branch for this version of the documentation
 58 |     'github_version': 'main',
 59 | 
 60 |     # Change to the folder that contains the documentation
 61 |     # (usually "/" or "/docs/")
 62 |     'github_folder': '/',
 63 | 
 64 |     # Change to an empty value if your GitHub repo doesn't have issues enabled.
 65 |     # This will disable the feedback button and the issue link in the footer.
 66 |     'github_issues': 'enabled'
 67 | }
 68 | 
 69 | ############################################################
 70 | ### Redirects
 71 | ############################################################
 72 | 
 73 | # Set up redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html)
 74 | # For example: 'explanation/old-name.html': '../how-to/prettify.html',
 75 | 
 76 | redirects = {}
 77 | 
 78 | ############################################################
 79 | ### Link checker exceptions
 80 | ############################################################
 81 | 
 82 | # Links to ignore when checking links
 83 | 
 84 | linkcheck_ignore = [
 85 |     'http://127.0.0.1:8000'
 86 |     ]
 87 | 
 88 | ############################################################
 89 | ### Additions to default configuration
 90 | ############################################################
 91 | 
 92 | ## The following settings are appended to the default configuration.
 93 | ## Use them to extend the default functionality.
 94 | 
 95 | # Add extensions
 96 | custom_extensions = []
 97 | 
 98 | # Add files or directories that should be excluded from processing.
 99 | custom_excludes = []
100 | 
101 | # Add CSS files (located in .sphinx/_static/)
102 | custom_html_css_files = []
103 | 
104 | # Add JavaScript files (located in .sphinx/_static/)
105 | custom_html_js_files = []
106 | 
107 | ## The following settings override the default configuration.
108 | 
109 | # Specify a reST string that is included at the end of each file.
110 | # If commented out, use the default (which pulls the reuse/links.txt
111 | # file into each reST file).
112 | # custom_rst_epilog = ''
113 | 
114 | # By default, the documentation includes a feedback button at the top.
115 | # You can disable it by setting the following configuration to True.
116 | disable_feedback_button = False
117 | 
118 | ############################################################
119 | ### Additional configuration
120 | ############################################################
121 | 
122 | ## Add any configuration that is not covered by the common conf.py file.
123 | 


--------------------------------------------------------------------------------
/doc-cheat-sheet-myst.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | orphan: true
  3 | myst:
  4 |     substitutions:
  5 |       reuse_key: "This is **included** text."
  6 |       advanced_reuse_key: "This is a substitution that includes a code block:
  7 |                          ```
  8 |                          code block
  9 |                          ```"
 10 | ---
 11 | 
 12 | (cheat-sheet-myst)=
 13 | # Markdown/MyST cheat sheet
 14 | 
 15 | This file contains the syntax for commonly used Markdown and MyST markup.
 16 | Open it in your text editor to quickly copy and paste the markup you need.
 17 | 
 18 | 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.
 19 | 
 20 | ## H2 heading
 21 | 
 22 | ### H3 heading
 23 | 
 24 | #### H4 heading
 25 | 
 26 | ##### H5 heading
 27 | 
 28 | ## Inline formatting
 29 | 
 30 | - {guilabel}`UI element`
 31 | - `code`
 32 | - {command}`command`
 33 | - {kbd}`Key`
 34 | - *Italic*
 35 | - **Bold**
 36 | 
 37 | ## Code blocks
 38 | 
 39 | Start a code block:
 40 | 
 41 |     code:
 42 |       - example: true
 43 | 
 44 | ```
 45 | # Demonstrate a code block
 46 | code:
 47 |   - example: true
 48 | ```
 49 | 
 50 | ```yaml
 51 | # Demonstrate a code block
 52 | code:
 53 |   - example: true
 54 | ```
 55 | 
 56 | (_a_section_target)=
 57 | ## Links
 58 | 
 59 | - [Canonical website](https://canonical.com/)
 60 | - https:/<span></span>/canonical.com/
 61 | - {ref}`a_section_target`
 62 | - {ref}`Link text <a_section_target>`
 63 | - {doc}`index`
 64 | - {doc}`Link text <index>`
 65 | 
 66 | 
 67 | ## Navigation
 68 | 
 69 | Use the following syntax::
 70 | 
 71 |     ```{toctree}
 72 |     :hidden:
 73 | 
 74 |     sub-page1
 75 |     sub-page2
 76 |     ```
 77 | 
 78 | ## Lists
 79 | 
 80 | 1. Step 1
 81 |    - Item 1
 82 |      * Sub-item
 83 |    - Item 2
 84 |      1. Sub-step 1
 85 |      1. Sub-step 2
 86 | 1. Step 2
 87 |    1. Sub-step 1
 88 |       - Item
 89 |    1. Sub-step 2
 90 | 
 91 | Term 1
 92 | : Definition
 93 | 
 94 | Term 2
 95 | : Definition
 96 | 
 97 | ## Tables
 98 | 
 99 | ## Markdown tables
100 | 
101 | | Header 1                           | Header 2 |
102 | |------------------------------------|----------|
103 | | Cell 1<br>Second paragraph         | Cell 2   |
104 | | Cell 3                             | Cell 4   |
105 | 
106 | Centred:
107 | 
108 | | Header 1                           | Header 2 |
109 | |:----------------------------------:|:--------:|
110 | | Cell 1<br>Second paragraph         | Cell 2   |
111 | | Cell 3                             | Cell 4   |
112 | 
113 | ## List tables
114 | 
115 | ```{list-table}
116 |    :header-rows: 1
117 | 
118 | * - Header 1
119 |   - Header 2
120 | * - Cell 1
121 | 
122 |     Second paragraph
123 |   - Cell 2
124 | * - Cell 3
125 |   - Cell 4
126 | ```
127 | 
128 | Centred:
129 | 
130 | ```{list-table}
131 |    :header-rows: 1
132 |    :align: center
133 | 
134 | * - Header 1
135 |   - Header 2
136 | * - Cell 1
137 | 
138 |     Second paragraph
139 |   - Cell 2
140 | * - Cell 3
141 |   - Cell 4
142 | ```
143 | 
144 | ## Notes
145 | 
146 | ```{note}
147 | A note.
148 | ```
149 | 
150 | ```{tip}
151 | A tip.
152 | ```
153 | 
154 | ```{important}
155 | Important information
156 | ```
157 | 
158 | ```{caution}
159 | This might damage your hardware!
160 | ```
161 | 
162 | ## Images
163 | 
164 | ![Alt text](https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png)
165 | 
166 | ```{figure} https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
167 |    :width: 100px
168 |    :alt: Alt text
169 | 
170 |    Figure caption
171 | ```
172 | 
173 | ## Reuse
174 | 
175 | ### Keys
176 | 
177 | Keys can be defined at the top of a file, or in a `myst_substitutions` option in `conf.py`.
178 | 
179 | {{reuse_key}}
180 | 
181 | {{advanced_reuse_key}}
182 | 
183 | ### File inclusion
184 | 
185 | ```{include} index.rst
186 |    :start-after: include_start
187 |    :end-before: include_end
188 | ```
189 | 
190 | ## Tabs
191 | 
192 | ````{tabs}
193 | ```{group-tab} Tab 1
194 | 
195 | Content Tab 1
196 | ```
197 | 
198 | ```{group-tab} Tab 2
199 | Content Tab 2
200 | ```
201 | ````
202 | 
203 | ## Glossary
204 | 
205 | ```{glossary}
206 | 
207 | some term
208 |   Definition of the example term.
209 | ```
210 | 
211 | {term}`some term`
212 | 
213 | ## More useful markup
214 | 
215 | - ```{versionadded} X.Y
216 | - {abbr}`API (Application Programming Interface)`
217 | 
218 | ----
219 | 
220 | ## Custom extensions
221 | 
222 | Related links at the top of the page (surrounded by `---`):
223 | 
224 |     relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com)
225 |     discourse: 12345
226 | 
227 | Terms that should not be checked by the spelling checker: {spellexception}`PurposelyWrong`
228 | 
229 | A terminal view with input and output:
230 | 
231 | ```{terminal}
232 |    :input: command
233 |    :user: root
234 |    :host: vampyr
235 | 
236 | the output
237 | ```
238 | 
239 | A link to a YouTube video:
240 | 
241 | ```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0
242 |    :title: Demo
243 | ```
244 | 


--------------------------------------------------------------------------------
/.sphinx/_static/custom.css:
--------------------------------------------------------------------------------
  1 | /** Fix the font weight (300 for normal, 400 for slightly bold) **/
  2 | 
  3 | div.page, h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head {
  4 |     font-weight: 300
  5 | }
  6 | 
  7 | .toc-tree li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt {
  8 |     font-weight: 400;
  9 | }
 10 | 
 11 | /** Table styling **/
 12 | 
 13 | th.head {
 14 |     text-transform: uppercase;
 15 |     font-size: var(--font-size--small);
 16 | }
 17 | 
 18 | table.docutils {
 19 |     border: 0;
 20 |     box-shadow: none;
 21 |     width:100%;
 22 | }
 23 | 
 24 | table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child {
 25 |     border-right: none;
 26 |     border-left: none;
 27 | }
 28 | 
 29 | /* Allow to centre text horizontally in table data cells */
 30 | table.align-center {
 31 |     text-align: center !important;
 32 | }
 33 | 
 34 | /** No rounded corners **/
 35 | 
 36 | .admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight {
 37 |     border-radius: 0;
 38 | }
 39 | 
 40 | /** Admonition styling **/
 41 | 
 42 | .admonition {
 43 |     border-top: 1px solid #d9d9d9;
 44 |     border-right: 1px solid #d9d9d9;
 45 |     border-bottom: 1px solid #d9d9d9;
 46 | }
 47 | 
 48 | /** Color for the "copy link" symbol next to headings **/
 49 | 
 50 | a.headerlink {
 51 |     color: var(--color-brand-primary);
 52 | }
 53 | 
 54 | /** Line to the left of the current navigation entry **/
 55 | 
 56 | .sidebar-tree li.current-page {
 57 |     border-left: 2px solid var(--color-brand-primary);
 58 | }
 59 | 
 60 | /** Some tweaks for issue #16 **/
 61 | 
 62 | [role="tablist"] {
 63 |     border-bottom: 1px solid var(--color-sidebar-item-background--hover);
 64 | }
 65 | 
 66 | .sphinx-tabs-tab[aria-selected="true"] {
 67 |     border: 0;
 68 |     border-bottom: 2px solid var(--color-brand-primary);
 69 |     background-color: var(--color-sidebar-item-background--current);
 70 |     font-weight:300;
 71 | }
 72 | 
 73 | .sphinx-tabs-tab{
 74 |     color: var(--color-brand-primary);
 75 |     font-weight:300;
 76 | }
 77 | 
 78 | .sphinx-tabs-panel {
 79 |     border: 0;
 80 |     border-bottom: 1px solid var(--color-sidebar-item-background--hover);
 81 |     background: var(--color-background-primary);
 82 | }
 83 | 
 84 | button.sphinx-tabs-tab:hover {
 85 |     background-color: var(--color-sidebar-item-background--hover);
 86 | }
 87 | 
 88 | /** Custom classes to fix scrolling in tables by decreasing the
 89 |     font size or breaking certain columns.
 90 |     Specify the classes in the Markdown file with, for example:
 91 |     ```{rst-class} break-col-4 min-width-4-8
 92 |     ```
 93 | **/
 94 | 
 95 | table.dec-font-size {
 96 |     font-size: smaller;
 97 | }
 98 | table.break-col-1 td.text-left:first-child {
 99 |     word-break: break-word;
100 | }
101 | table.break-col-4 td.text-left:nth-child(4) {
102 |     word-break: break-word;
103 | }
104 | table.min-width-1-15 td.text-left:first-child {
105 |     min-width: 15em;
106 | }
107 | table.min-width-4-8 td.text-left:nth-child(4) {
108 |     min-width: 8em;
109 | }
110 | 
111 | /** Underline for abbreviations **/
112 | 
113 | abbr[title] {
114 |     text-decoration: underline solid #cdcdcd;
115 | }
116 | 
117 | /** Use the same style for right-details as for left-details **/
118 | .bottom-of-page .right-details {
119 |     font-size: var(--font-size--small);
120 |     display: block;
121 | }
122 | 
123 | /** Version switcher */
124 | button.version_select {
125 |   color: var(--color-foreground-primary);
126 |   background-color: var(--color-toc-background);
127 |   padding: 5px 10px;
128 |   border: none;
129 | }
130 | 
131 | .version_select:hover, .version_select:focus {
132 |     background-color: var(--color-sidebar-item-background--hover);
133 | }
134 | 
135 | .version_dropdown {
136 |   position: relative;
137 |   display: inline-block;
138 |   text-align: right;
139 |   font-size: var(--sidebar-item-font-size);
140 | }
141 | 
142 | .available_versions {
143 |   display: none;
144 |   position: absolute;
145 |   right: 0px;
146 |   background-color: var(--color-toc-background);
147 |   box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2);
148 |   z-index: 11;
149 | }
150 | 
151 | .available_versions a {
152 |   color: var(--color-foreground-primary);
153 |   padding: 12px 16px;
154 |   text-decoration: none;
155 |   display: block;
156 | }
157 | 
158 | .available_versions a:hover {background-color: var(--color-sidebar-item-background--current)}
159 | 
160 | .show {display:block;}
161 | 
162 | /** Fix for nested numbered list - the nested list is lettered **/
163 | ol.arabic ol.arabic {
164 |   list-style: lower-alpha;
165 | }
166 | 
167 | /** Make expandable sections look like links **/
168 | details summary {
169 |     color: var(--color-link);
170 | }
171 | 
172 | /** Fix the styling of the version box for readthedocs **/
173 | 
174 | #furo-readthedocs-versions .rst-versions, #furo-readthedocs-versions .rst-current-version, #furo-readthedocs-versions:focus-within .rst-current-version, #furo-readthedocs-versions:hover .rst-current-version  {
175 |     background: var(--color-sidebar-item-background--hover);
176 | }
177 | 
178 | .rst-versions .rst-other-versions dd a {
179 |     color: var(--color-link);
180 | }
181 | 
182 | #furo-readthedocs-versions:focus-within .rst-current-version .fa-book, #furo-readthedocs-versions:hover .rst-current-version .fa-book, .rst-versions .rst-other-versions {
183 |     color: var(--color-sidebar-link-text);
184 | }
185 | 
186 | .rst-versions .rst-current-version {
187 |     color: var(--color-version-popup);
188 |     font-weight: bolder;
189 | }
190 | 


--------------------------------------------------------------------------------
/doc-cheat-sheet.rst:
--------------------------------------------------------------------------------
  1 | :orphan:
  2 | 
  3 | .. _cheat-sheet:
  4 | 
  5 | reStructuredText cheat sheet
  6 | ============================
  7 | 
  8 | This file contains the syntax for commonly used reST markup.
  9 | Open it in your text editor to quickly copy and paste the markup you need.
 10 | 
 11 | See the `reStructuredText style guide <https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/>`_ for detailed information and conventions.
 12 | 
 13 | 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.
 14 | 
 15 | H2 heading
 16 | ----------
 17 | 
 18 | H3 heading
 19 | ~~~~~~~~~~
 20 | 
 21 | H4 heading
 22 | ^^^^^^^^^^
 23 | 
 24 | H5 heading
 25 | ..........
 26 | 
 27 | Inline formatting
 28 | -----------------
 29 | 
 30 | - :guilabel:`UI element`
 31 | - ``code``
 32 | - :file:`file path`
 33 | - :command:`command`
 34 | - :kbd:`Key`
 35 | - *Italic*
 36 | - **Bold**
 37 | 
 38 | Code blocks
 39 | -----------
 40 | 
 41 | Start a code block::
 42 | 
 43 |      code:
 44 |        - example: true
 45 | 
 46 | .. code::
 47 | 
 48 |      # Demonstrate a code block
 49 |      code:
 50 |        - example: true
 51 | 
 52 | .. code:: yaml
 53 | 
 54 |      # Demonstrate a code block
 55 |      code:
 56 |        - example: true
 57 | 
 58 | .. _a_section_target:
 59 | 
 60 | Links
 61 | -----
 62 | 
 63 | - `Canonical website <https://canonical.com/>`_
 64 | - `Canonical website`_ (defined in ``reuse/links.txt`` or at the bottom of the page)
 65 | - https:\ //canonical.com/
 66 | - :ref:`a_section_target`
 67 | - :ref:`Link text <a_section_target>`
 68 | - :doc:`index`
 69 | - :doc:`Link text <index>`
 70 | 
 71 | 
 72 | Navigation
 73 | ----------
 74 | 
 75 | Use the following syntax::
 76 | 
 77 |   .. toctree::
 78 |      :hidden:
 79 | 
 80 |      sub-page1
 81 |      sub-page2
 82 | 
 83 | 
 84 | Lists
 85 | -----
 86 | 
 87 | 1. Step 1
 88 | 
 89 |    - Item 1
 90 | 
 91 |      * Sub-item
 92 |    - Item 2
 93 | 
 94 |      i. Sub-step 1
 95 |      #. Sub-step 2
 96 | #. Step 2
 97 | 
 98 |    a. Sub-step 1
 99 | 
100 |       - Item
101 |    #. Sub-step 2
102 | 
103 | Term 1:
104 |   Definition
105 | Term 2:
106 |   Definition
107 | 
108 | Tables
109 | ------
110 | 
111 | +----------------------+------------+
112 | | Header 1             | Header 2   |
113 | +======================+============+
114 | | Cell 1               | Cell 2     |
115 | |                      |            |
116 | | Second paragraph     |            |
117 | +----------------------+------------+
118 | | Cell 3               | Cell 4     |
119 | +----------------------+------------+
120 | 
121 | .. list-table::
122 |    :header-rows: 1
123 | 
124 |    * - Header 1
125 |      - Header 2
126 |    * - Cell 1
127 | 
128 |        Second paragraph
129 |      - Cell 2
130 |    * - Cell 3
131 |      - Cell 4
132 | 
133 | .. rst-class:: align-center
134 | 
135 |    +----------------------+------------+
136 |    | Header 1             | Header 2   |
137 |    +======================+============+
138 |    | Cell 1               | Cell 2     |
139 |    |                      |            |
140 |    | Second paragraph     |            |
141 |    +----------------------+------------+
142 |    | Cell 3               | Cell 4     |
143 |    +----------------------+------------+
144 | 
145 | .. list-table::
146 |    :header-rows: 1
147 |    :align: center
148 | 
149 |    * - Header 1
150 |      - Header 2
151 |    * - Cell 1
152 | 
153 |        Second paragraph
154 |      - Cell 2
155 |    * - Cell 3
156 |      - Cell 4
157 | 
158 | Notes
159 | -----
160 | 
161 | .. note::
162 |    A note.
163 | 
164 | .. tip::
165 |    A tip.
166 | 
167 | .. important::
168 |    Important information
169 | 
170 | .. caution::
171 |    This might damage your hardware!
172 | 
173 | Images
174 | ------
175 | 
176 | .. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
177 | 
178 | .. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png
179 |    :width: 100px
180 |    :alt: Alt text
181 | 
182 |    Figure caption
183 | 
184 | Reuse
185 | -----
186 | 
187 | .. |reuse_key| replace:: This is **included** text.
188 | 
189 | |reuse_key|
190 | 
191 | .. include:: index.rst
192 |    :start-after: include_start
193 |    :end-before: include_end
194 | 
195 | Tabs
196 | ----
197 | 
198 | .. tabs::
199 | 
200 |    .. group-tab:: Tab 1
201 | 
202 |       Content Tab 1
203 | 
204 |    .. group-tab:: Tab 2
205 | 
206 |       Content Tab 2
207 | 
208 | 
209 | Glossary
210 | --------
211 | 
212 | .. glossary::
213 | 
214 |    example term
215 |      Definition of the example term.
216 | 
217 | :term:`example term`
218 | 
219 | More useful markup
220 | ------------------
221 | 
222 | - .. versionadded:: X.Y
223 | - | Line 1
224 |   | Line 2
225 |   | Line 3
226 | - .. This is a comment
227 | - :abbr:`API (Application Programming Interface)`
228 | 
229 | ----
230 | 
231 | Custom extensions
232 | -----------------
233 | 
234 | Related links at the top of the page::
235 | 
236 |   :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com)
237 |   :discourse: 12345
238 | 
239 | Terms that should not be checked by the spelling checker: :spellexception:`PurposelyWrong`
240 | 
241 | A terminal view with input and output:
242 | 
243 | .. terminal::
244 |    :input: command
245 |    :user: root
246 |    :host: vampyr
247 | 
248 |    the output
249 | 
250 | A link to a YouTube video:
251 | 
252 | .. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0
253 |           :title: Demo
254 | 
255 | 
256 | 
257 | .. LINKS
258 | .. _Canonical website: https://canonical.com/
259 | 


--------------------------------------------------------------------------------
/conf.py:
--------------------------------------------------------------------------------
  1 | import sys
  2 | 
  3 | sys.path.append('./')
  4 | from custom_conf import *
  5 | 
  6 | # Configuration file for the Sphinx documentation builder.
  7 | # You should not do any modifications to this file. Put your custom
  8 | # configuration into the custom_conf.py file.
  9 | # If you need to change this file, contribute the changes upstream.
 10 | #
 11 | # For the full list of built-in configuration values, see the documentation:
 12 | # https://www.sphinx-doc.org/en/master/usage/configuration.html
 13 | 
 14 | ############################################################
 15 | ### Extensions
 16 | ############################################################
 17 | 
 18 | extensions = [
 19 |     'sphinx_design',
 20 |     'sphinx_tabs.tabs',
 21 |     'sphinx_reredirects',
 22 |     'youtube-links',
 23 |     'related-links',
 24 |     'custom-rst-roles',
 25 |     'terminal-output',
 26 |     'sphinx_copybutton',
 27 |     'sphinxext.opengraph',
 28 |     'myst_parser',
 29 |     'sphinxcontrib.jquery'
 30 |     ]
 31 | extensions.extend(custom_extensions)
 32 | 
 33 | ### Configuration for extensions
 34 | 
 35 | # Additional MyST syntax
 36 | myst_enable_extensions = [
 37 |     'substitution',
 38 |     'deflist'
 39 | ]
 40 | 
 41 | # Used for related links
 42 | if 'discourse' in html_context:
 43 |     html_context['discourse_prefix'] = html_context['discourse'] + '/t/'
 44 | 
 45 | # Default image for OGP (to prevent font errors, see
 46 | # https://github.com/canonical/sphinx-docs-starter-pack/pull/54 )
 47 | if not 'ogp_image' in locals():
 48 |     ogp_image = 'https://assets.ubuntu.com/v1/253da317-image-document-ubuntudocs.svg'
 49 | 
 50 | ############################################################
 51 | ### General configuration
 52 | ############################################################
 53 | 
 54 | exclude_patterns = [
 55 |     '_build',
 56 |     'Thumbs.db',
 57 |     '.DS_Store',
 58 |     '.sphinx',
 59 |     'doc-cheat-sheet*',
 60 | ]
 61 | exclude_patterns.extend(custom_excludes)
 62 | 
 63 | rst_epilog = '''
 64 | .. include:: /reuse/links.txt
 65 | '''
 66 | if 'custom_rst_epilog' in locals():
 67 |     rst_epilog = custom_rst_epilog
 68 | 
 69 | source_suffix = {
 70 |     '.rst': 'restructuredtext',
 71 |     '.md': 'markdown',
 72 | }
 73 | 
 74 | if not 'conf_py_path' in html_context and 'github_folder' in html_context:
 75 |     html_context['conf_py_path'] = html_context['github_folder']
 76 | 
 77 | ############################################################
 78 | ### Styling
 79 | ############################################################
 80 | 
 81 | # Find the current builder
 82 | builder = 'dirhtml'
 83 | if '-b' in sys.argv:
 84 |     builder = sys.argv[sys.argv.index('-b')+1]
 85 | 
 86 | # Setting templates_path for epub makes the build fail
 87 | if builder == 'dirhtml' or builder == 'html':
 88 |     templates_path = ['.sphinx/_templates']
 89 | 
 90 | # Theme configuration
 91 | html_theme = 'furo'
 92 | html_last_updated_fmt = ''
 93 | html_permalinks_icon = '¶'
 94 | html_theme_options = {
 95 |     'light_css_variables': {
 96 |         'font-stack': 'Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif',
 97 |         'font-stack--monospace': 'Ubuntu Mono, Consolas, Monaco, Courier, monospace',
 98 |         'color-foreground-primary': '#111',
 99 |         'color-foreground-secondary': 'var(--color-foreground-primary)',
100 |         'color-foreground-muted': '#333',
101 |         'color-background-secondary': '#FFF',
102 |         'color-background-hover': '#f2f2f2',
103 |         'color-brand-primary': '#111',
104 |         'color-brand-content': '#06C',
105 |         'color-api-background': '#cdcdcd',
106 |         'color-inline-code-background': 'rgba(0,0,0,.03)',
107 |         'color-sidebar-link-text': '#111',
108 |         'color-sidebar-item-background--current': '#ebebeb',
109 |         'color-sidebar-item-background--hover': '#f2f2f2',
110 |         'toc-font-size': 'var(--font-size--small)',
111 |         'color-admonition-title-background--note': 'var(--color-background-primary)',
112 |         'color-admonition-title-background--tip': 'var(--color-background-primary)',
113 |         'color-admonition-title-background--important': 'var(--color-background-primary)',
114 |         'color-admonition-title-background--caution': 'var(--color-background-primary)',
115 |         'color-admonition-title--note': '#24598F',
116 |         'color-admonition-title--tip': '#24598F',
117 |         'color-admonition-title--important': '#C7162B',
118 |         'color-admonition-title--caution': '#F99B11',
119 |         'color-highlighted-background': '#EbEbEb',
120 |         'color-link-underline': 'var(--color-background-primary)',
121 |         'color-link-underline--hover': 'var(--color-background-primary)',
122 |         'color-version-popup': '#772953'
123 |     },
124 |     'dark_css_variables': {
125 |         'color-foreground-secondary': 'var(--color-foreground-primary)',
126 |         'color-foreground-muted': '#CDCDCD',
127 |         'color-background-secondary': 'var(--color-background-primary)',
128 |         'color-background-hover': '#666',
129 |         'color-brand-primary': '#fff',
130 |         'color-brand-content': '#06C',
131 |         'color-sidebar-link-text': '#f7f7f7',
132 |         'color-sidebar-item-background--current': '#666',
133 |         'color-sidebar-item-background--hover': '#333',
134 |         'color-admonition-background': 'transparent',
135 |         'color-admonition-title-background--note': 'var(--color-background-primary)',
136 |         'color-admonition-title-background--tip': 'var(--color-background-primary)',
137 |         'color-admonition-title-background--important': 'var(--color-background-primary)',
138 |         'color-admonition-title-background--caution': 'var(--color-background-primary)',
139 |         'color-admonition-title--note': '#24598F',
140 |         'color-admonition-title--tip': '#24598F',
141 |         'color-admonition-title--important': '#C7162B',
142 |         'color-admonition-title--caution': '#F99B11',
143 |         'color-highlighted-background': '#666',
144 |         'color-link-underline': 'var(--color-background-primary)',
145 |         'color-link-underline--hover': 'var(--color-background-primary)',
146 |         'color-version-popup': '#F29879'
147 |     },
148 | }
149 | 
150 | ############################################################
151 | ### Additional files
152 | ############################################################
153 | 
154 | html_static_path = ['.sphinx/_static']
155 | 
156 | html_css_files = [
157 |     'custom.css',
158 |     'header.css',
159 |     'github_issue_links.css',
160 | ]
161 | html_css_files.extend(custom_html_css_files)
162 | 
163 | html_js_files = ['header-nav.js']
164 | if 'github_issues' in html_context and html_context['github_issues'] and not disable_feedback_button:
165 |     html_js_files.append('github_issue_links.js')
166 | html_js_files.extend(custom_html_js_files)
167 | 


--------------------------------------------------------------------------------
/readme.rst:
--------------------------------------------------------------------------------
  1 | Documentation starter pack
  2 | ==========================
  3 | 
  4 | 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.
  5 | 
  6 | Then go through the following sections to use this starter pack to set up your docs repository.
  7 | 
  8 | Set up your documentation repository
  9 | ------------------------------------
 10 | 
 11 | You can either create a standalone documentation project based on this repository or include the files from this repository in a dedicated documentation folder in an existing code repository.
 12 | 
 13 | **Note:** We're planning to provide the contents of this repository as an installable package in the future, but currently, you need to copy and update the required files manually.
 14 | 
 15 | Standalone documentation repository
 16 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 17 | 
 18 | To create a standalone documentation repository, clone this starter pack repository, `update the configuration <#configure-the-documentation>`_, and then commit all files to your own documentation repository.
 19 | 
 20 | You don't need to move any files, and you don't need to do any special configuration on Read the Docs.
 21 | 
 22 | Documentation in a code repository
 23 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 24 | 
 25 | To add documentation to an existing code repository:
 26 | 
 27 | #. create a directory called ``docs`` at the root of the code repository
 28 | #. populate the above directory with the contents of the starter pack
 29 |    repository (with the exception of the ``.git`` directory)
 30 | #. copy the file(s) located in the ``docs/.github/workflows`` directory into
 31 |    the code repository's ``.github/workflows`` directory
 32 | #. in the above workflow file(s), set the values of the ``working-directory``
 33 |    and ``workdir`` fields to ``docs``
 34 | #. in file ``docs/.readthedocs.yaml`` set the following:
 35 | 
 36 |    * ``configuration: docs/conf.py``
 37 |    * ``requirements: docs/.sphinx/requirements.txt``
 38 | 
 39 | .. note::
 40 | 
 41 |    When configuring RTD itself for your project, the setting **Path for
 42 |    .readthedocs.yaml** (under **Advanced Settings**) will need to be given the
 43 |    value of "docs/.readthedocs.yaml".
 44 | 
 45 | Getting started
 46 | ---------------
 47 | 
 48 | There are make targets defined in the ``Makefile`` that do various things. To
 49 | get started, we will:
 50 | 
 51 | * install prerequisite software
 52 | * view the documentation
 53 | 
 54 | Install prerequisite software
 55 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 56 | 
 57 | To install the prerequisites:
 58 | 
 59 | .. code-block:: none
 60 | 
 61 |    make install
 62 | 
 63 | This will create a virtual environment (``.sphinx/venv``) and install
 64 | dependency software (``.sphinx/requirements.txt``) within it.
 65 | 
 66 | A complete set of pinned, known-working dependencies is included in
 67 | ``.sphinx/pinned-requirements.txt``.
 68 | 
 69 | View the documentation
 70 | ~~~~~~~~~~~~~~~~~~~~~~
 71 | 
 72 | To view the documentation:
 73 | 
 74 | .. code-block:: none
 75 | 
 76 |    make run
 77 | 
 78 | This will do several things:
 79 | 
 80 | * activate the virtual environment
 81 | * build the documentation
 82 | * serve the documentation on **127.0.0.1:8000**
 83 | * rebuild the documentation each time a file is saved
 84 | * send a reload page signal to the browser when the documentation is rebuilt
 85 | 
 86 | The ``run`` target is therefore very convenient when preparing to submit a
 87 | change to the documentation. For a more manual approach, to strictly build and
 88 | serve content, explore the ``html`` and ``serve`` make targets, respectively.
 89 | 
 90 | Configure the documentation
 91 | ---------------------------
 92 | 
 93 | You must modify some of the default configuration to suit your project.
 94 | To simplify keeping your documentation in sync with the starter pack, all custom configuration is located in the ``custom_conf.py`` file.
 95 | You should never modify the common ``conf.py`` file.
 96 | 
 97 | Go through all settings in the ``Project information`` section of the ``custom_conf.py`` file and update them for your project.
 98 | 
 99 | See the following sections for further customisation.
100 | 
101 | Configure the header
102 | ~~~~~~~~~~~~~~~~~~~~
103 | 
104 | By default, the header contains your product tag, product name (taken from the ``project`` setting in the ``custom_conf.py`` file), a link to your product page, and a drop-down menu for "More resources" that contains links to Discourse and GitHub.
105 | 
106 | You can change any of those links or add further links to the "More resources" drop-down by editing the ``.sphinx/_templates/header.html`` file.
107 | For example, you might want to add links to announcements, tutorials, getting started guides, or videos that are not part of the documentation.
108 | 
109 | Configure the spelling check
110 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111 | 
112 | If your documentation uses US English instead of UK English, change this in the
113 | ``.sphinx/spellingcheck.yaml`` file.
114 | 
115 | To add exceptions for words the spelling check marks as wrong even though they are correct, edit the ``.wordlist.txt`` file.
116 | 
117 | Configure the link check
118 | ~~~~~~~~~~~~~~~~~~~~~~~~
119 | 
120 | If you have links in the documentation that you don't want to be checked (for
121 | example, because they are local links or give random errors even though they
122 | work), you can add them to the ``linkcheck_ignore`` variable in the ``custom_conf.py`` file.
123 | 
124 | Activate/deactivate feedback button
125 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126 | 
127 | A feedback button is included by default, which appears at the top of each page
128 | in the documentation. It redirects users to your GitHub issues page, and
129 | populates an issue for them with details of the page they were on when they
130 | clicked the button.
131 | 
132 | If your project does not use GitHub issues, set the ``github_issues`` variable
133 | in the ``custom_conf.py`` file to an empty value to disable both the feedback button
134 | and the issue link in the footer.
135 | If you want to deactivate only the feedback button, but keep the link in the
136 | footer, set ``disable_feedback_button`` in the ``custom_conf.py`` file to ``True``.
137 | 
138 | Add redirects
139 | ~~~~~~~~~~~~~
140 | 
141 | You can add redirects to make sure existing links and bookmarks continue working when you move files around.
142 | To do so, specify the old and new paths in the ``redirects`` setting of the ``custom_conf.py`` file.
143 | 
144 | Add custom configuration
145 | ~~~~~~~~~~~~~~~~~~~~~~~~
146 | 
147 | To add custom configurations for your project, see the ``Additions to default configuration`` and ``Additional configuration`` sections in the ``custom_conf.py`` file.
148 | These can be used to extend or override the common configuration, or to define additional configuration that is not covered by the common ``conf.py`` file.
149 | 
150 | Change log
151 | ----------
152 | 
153 | See the `change log <https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log>`_ for a list of relevant changes to the starter pack.
154 | 


--------------------------------------------------------------------------------