diff --git a/docs/doc-cheat-sheet-myst.md b/docs/doc-cheat-sheet-myst.md deleted file mode 100644 index 19b07f531..000000000 --- a/docs/doc-cheat-sheet-myst.md +++ /dev/null @@ -1,243 +0,0 @@ ---- -orphan: true -myst: - substitutions: - reuse_key: "This is **included** text." - advanced_reuse_key: "This is a substitution that includes a code block: - ``` - code block - ```" ---- - -(cheat-sheet-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 - -### H3 heading - -#### H4 heading - -##### H5 heading - -## 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 -``` - -```yaml -# Demonstrate a code block -code: - - example: true -``` - -(_a_section_target)= -## Links - -- [Canonical website](https://canonical.com/) -- https://canonical.com/ -- {ref}`a_section_target` -- {ref}`Link text ` -- {doc}`index` -- {doc}`Link text ` - - -## 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 - -## Markdown tables - -| Header 1 | Header 2 | -|------------------------------------|----------| -| Cell 1
Second paragraph | Cell 2 | -| Cell 3 | Cell 4 | - -Centred: - -| Header 1 | Header 2 | -|:----------------------------------:|:--------:| -| Cell 1
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.rst - :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 terminal view with input and output: - -```{terminal} - :input: command - :user: root - :host: vampyr - -the output -``` - -A link to a YouTube video: - -```{youtube} https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo -``` diff --git a/docs/doc-cheat-sheet.rst b/docs/doc-cheat-sheet.rst deleted file mode 100644 index b12ebcdf7..000000000 --- a/docs/doc-cheat-sheet.rst +++ /dev/null @@ -1,258 +0,0 @@ -:orphan: - -.. _cheat-sheet: - -reStructuredText cheat sheet -============================ - -This file contains the syntax for commonly used reST markup. -Open it in your text editor to quickly copy and paste the markup you need. - -See the `reStructuredText style guide `_ for detailed information and conventions. - -Also see the `Sphinx reStructuredText Primer `_ for more details on reST, and the `Canonical Documentation Style Guide `_ for general style conventions. - -H2 heading ----------- - -H3 heading -~~~~~~~~~~ - -H4 heading -^^^^^^^^^^ - -H5 heading -.......... - -Inline formatting ------------------ - -- :guilabel:`UI element` -- ``code`` -- :file:`file path` -- :command:`command` -- :kbd:`Key` -- *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 `_ -- `Canonical website`_ (defined in ``reuse/links.txt`` or at the bottom of the page) -- https:\ //canonical.com/ -- :ref:`a_section_target` -- :ref:`Link text ` -- :doc:`index` -- :doc:`Link text ` - - -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 - -.. rst-class:: align-center - - +----------------------+------------+ - | Header 1 | Header 2 | - +======================+============+ - | Cell 1 | Cell 2 | - | | | - | Second paragraph | | - +----------------------+------------+ - | Cell 3 | Cell 4 | - +----------------------+------------+ - -.. 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 ------- - -.. 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:: index.rst - :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:: - - 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 - -Terms that should not be checked by the spelling checker: :spellexception:`PurposelyWrong` - -A terminal view with input and output: - -.. terminal:: - :input: command - :user: root - :host: vampyr - - the output - -A link to a YouTube video: - -.. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - - - -.. LINKS -.. _Canonical website: https://canonical.com/ diff --git a/docs/readme.rst b/docs/readme.rst deleted file mode 100644 index fc6fd84ff..000000000 --- a/docs/readme.rst +++ /dev/null @@ -1,284 +0,0 @@ -Documentation starter pack -========================== - -See the `Sphinx and Read the Docs `_ 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. - -Set up your documentation repository ------------------------------------- - -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. - -**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. - -Standalone documentation repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To create a standalone documentation repository, clone this starter pack -repository, `update the configuration <#configure-the-documentation>`_, and -then commit all files to the documentation repository. - -You don't need to move any files, and you don't need to do any special -configuration on Read the Docs. - -Here is one way to do this for newly-created fictional docs repository -``canonical/alpha-docs``: - -.. code-block:: none - - git clone git@github.com:canonical/sphinx-docs-starter-pack alpha-docs - cd alpha-docs - rm -rf .git - git init - git branch -m main - UPDATE THE CONFIGURATION AND BUILD THE DOCS - git add -A - git commit -m "Import sphinx-docs-starter-pack" - git remote add upstream git@github.com:canonical/alpha-docs - git push -f upstream main - -Documentation in a code repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To add documentation to an existing code repository: - -#. create a directory called ``docs`` at the root of the code repository -#. populate the above directory with the contents of the starter pack - repository (with the exception of the ``.git`` directory) -#. copy the file(s) located in the ``docs/.github/workflows`` directory into - the code repository's ``.github/workflows`` directory -#. in the above workflow file(s), change the value of the ``working-directory`` field from ``.`` to ``docs`` -#. in file ``docs/.readthedocs.yaml`` set the following: - - * ``configuration: docs/conf.py`` - * ``requirements: docs/.sphinx/requirements.txt`` - -**Note:** When configuring RTD itself for your project, the setting "Path for -``.readthedocs.yaml``" (under **Advanced Settings**) will need to be given the -value of ``docs/.readthedocs.yaml``. - -Getting started ---------------- - -There are make targets defined in the ``Makefile`` that do various things. To -get started, we will: - -* install prerequisite software -* view the documentation - -Install prerequisite software -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To install the prerequisites: - -.. code-block:: none - - make install - -This will create a virtual environment (``.sphinx/venv``) and install -dependency software (``.sphinx/requirements.txt``) within it. - -**Note**: -By default, the starter pack uses the latest compatible version of all tools and does not pin its requirements. -This might change temporarily if there is an incompatibility with a new tool version. -There is therefore no need in using a tool like Renovate to automatically update the requirements. - -View the documentation -~~~~~~~~~~~~~~~~~~~~~~ - -To view the documentation: - -.. code-block:: none - - make run - -This will do several things: - -* activate the virtual environment -* build the documentation -* serve the documentation on **127.0.0.1:8000** -* rebuild the documentation each time a file is saved -* send a reload page signal to the browser when the documentation is rebuilt - -The ``run`` target is therefore very convenient when preparing to submit a -change to the documentation. - -Local checks -~~~~~~~~~~~~ - -Before committing and pushing changes, it's a good practice to run various checks locally to catch issues early in the development process. - -Local build -^^^^^^^^^^^ - -Run a clean build of the docs to surface any build errors that would occur in RTD: - -.. code-block:: none - - make clean-doc - make html - -Spelling check -^^^^^^^^^^^^^^ - -Ensure there are no spelling errors in the documentation: - -.. code-block:: shell - - make spelling - -Inclusive language check -^^^^^^^^^^^^^^^^^^^^^^^^ - -Ensure the documentation uses inclusive language: - -.. code-block:: shell - - make woke - -Link check -^^^^^^^^^^ - -Validate links within the documentation: - -.. code-block:: shell - - make linkcheck - -Configure the documentation ---------------------------- - -You must modify some of the default configuration to suit your project. -To simplify keeping your documentation in sync with the starter pack, all custom configuration is located in the ``custom_conf.py`` file. -You should never modify the common ``conf.py`` file. - -Go through all settings in the ``Project information`` section of the ``custom_conf.py`` file and update them for your project. - -See the following sections for further customisation. - -Configure the header -~~~~~~~~~~~~~~~~~~~~ - -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. - -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. -For example, you might want to add links to announcements, tutorials, getting started guides, or videos that are not part of the documentation. - -Configure the spelling check -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If your documentation uses US English instead of UK English, change this in the -``.sphinx/spellingcheck.yaml`` file. - -To add exceptions for words the spelling check marks as wrong even though they are correct, edit the ``.custom_wordlist.txt`` file. -You shouldn't edit ``.wordlist.txt``, because this file is maintained and updated centrally and contains words that apply across all projects. - -Configure the inclusive-language check -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If you can't avoid non-inclusive language in some cases, you'll need to -configure exemptions for them. - -In-file exemptions -^^^^^^^^^^^^^^^^^^ - -Suppose a reST file has a link to some site you don't control, and the address -contains "\m\a\s\t\e\r" — a non-inclusive word. You can't change the link, -but the remainder of the file must be checked for inclusive language. Here the -``woke`` tool's `next-line ignore -`_ feature is -useful, as follows. - -If the link is in-line, move the definition to a line of its own (e.g. among -``.. LINKS`` at the bottom of the file). Above the definition, invoke the -``wokeignore`` rule for the offending word: - -.. code-block:: ReST - - .. LINKS - .. wokeignore:rule=master - .. _link anchor: https://some-external-site.io/master/some-page.html - -Exempt an entire file -^^^^^^^^^^^^^^^^^^^^^ - -If it's necessary *and safe*, you can exempt a whole file from -inclusive-language checks. To exempt ``docs/foo/bar.rst`` for example, add the -following line to ``.wokeignore``: - -.. code-block:: none - - foo/bar.rst - -.. note:: - - For ``.wokeignore`` to take effect, you must also move it into your - project's root directory. If you leave it in ``docs/``, the ``woke`` tool - won't find it and no files will be exempt. - -Change checked file-types and locations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By default, only reST files are checked for inclusive language — and only those -in the documentation folder (usually ``docs/``) and its subfolders. To check -Markdown files for example, or files outside the ``docs/`` subtree, you must -change how the ``woke`` tool is invoked. - -The ``woke`` command is issued from ``docs/Makefile``. The command's syntax -is out of scope here — consult the `woke User Guide -`_. - -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 ``custom_conf.py`` file. - -Activate/deactivate feedback button -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A feedback button is included by default, which appears at the top of each page -in the documentation. It redirects users to your GitHub issues page, and -populates an issue for them with details of the page they were on when they -clicked the button. - -If your project does not use GitHub issues, set the ``github_issues`` variable -in the ``custom_conf.py`` file to an empty value to disable both the feedback button -and the issue link in the footer. -If you want to deactivate only the feedback button, but keep the link in the -footer, set ``disable_feedback_button`` in the ``custom_conf.py`` file to ``True``. - -Add redirects -~~~~~~~~~~~~~ - -You can add redirects to make sure existing links and bookmarks continue working when you move files around. -To do so, specify the old and new paths in the ``redirects`` setting of the ``custom_conf.py`` file. - -Add custom configuration -~~~~~~~~~~~~~~~~~~~~~~~~ - -To add custom configurations for your project, see the ``Additions to default configuration`` and ``Additional configuration`` sections in the ``custom_conf.py`` file. -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. - -(Optional) Synchronise GitHub issues to Jira --------------------------------------------- - -If you wish to sync issues from your documentation repository on GitHub to your -Jira board, configure the `GitHub/Jira sync bot `_ -by editing the ``.github/workflows/.jira_sync_config.yaml`` file appropriately. -In addition to updating this file, you must also apply server configuration -for this feature to work. For more information, see `server configuration details `_ -for the GitHub/Jira sync bot. - -The ``.jira_sync_config.yaml`` file that is included in the starter pack -contains configuration for syncing issues from the starter pack repository to -its documentation Jira board. -Therefore, it does not work out of the box for other repositories in GitHub, -and you must update it if you want to use the synchronisation feature. - -Change log ----------- - -See the `change log `_ for a list of relevant changes to the starter pack.