Merge pull request #254 from ru-fu/DOCPR-525-docs

Update documentation

README.rst

@@ -0,0 +1 @@
+See the documentation at https://canonical-starter-pack.readthedocs-hosted.com/use-canonical-sphinx-extension/

sp-docs/.custom_wordlist.txt

@@ -0,0 +1 @@
+WCAG

sp-docs/docs/automatic_checks.rst

@@ -0,0 +1,29 @@
+.. _automatic-checks:
+
+Automatic checks
+================
+
+The starter pack comes with several automatic checks that you can (and should!) run on your documentation before committing and pushing changes.
+
+The following checks are available:
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   /docs/automatic_checks_*
+
+Install prerequisite software
+-----------------------------
+
+Some of the tools used by the automatic checks might not be available by default on your system.
+To install them, you need ``snap`` and ``npm``::
+
+   sudo apt install npm snapd
+
+To install the validation tools:
+
+.. code-block:: bash
+
+   make woke-install
+   make pa11y-install

sp-docs/docs/automatic_checks_accessibility.rst

@@ -0,0 +1,42 @@
+.. _automatic-checks-accessibility:
+
+Accessibility check
+===================
+
+The accessibility check uses `Pa11y`_ to check for accessibility issues in the documentation output.
+
+It is configured to use the `Web Content Accessibility Guidelines (WCAG) 2.2`_, requiring `Level AA conformance`_.
+
+.. note::
+
+   The accessibility check is not yet required, since there are some issues within the starter pack itself.
+   We are working on resolving those.
+
+   For now, the check is implemented as non-blocking as part of our GitHub workflow.
+
+Install prerequisite software
+-----------------------------
+
+``Pa11y`` must be installed through ``npm``::
+
+   sudo apt install npm
+
+To install ``Pa11y``:
+
+.. code-block:: bash
+
+   make pa11y-install
+
+Run the accessibility check
+---------------------------
+
+Look for accessibility issues in rendered documentation::
+
+   make pa11y
+
+Configure the accessibility check
+---------------------------------
+
+The :file:`pa11y.json` file in the :file:`.sphinx` directory provides basic defaults.
+
+To browse the available settings and options, see ``Pa11y``'s `README <Pa11y readme_>`_ on GitHub.

sp-docs/docs/automatic_checks_inclusivelanguage.rst

@@ -0,0 +1,79 @@
+.. _automatic-checks-inclusivelanguage:
+
+Inclusive language check
+========================
+
+The inclusive language check uses `woke`_ to check for violations of inclusive language guidelines.
+
+Install prerequisite software
+-----------------------------
+
+To install ``woke``, you need ``snap``::
+
+   sudo apt install snapd
+
+To install ``woke``:
+
+.. code-block:: bash
+
+   make woke-install
+
+Run the inclusive language check
+--------------------------------
+
+Ensure the documentation uses inclusive language::
+
+   make woke
+
+Configure the inclusive language check
+--------------------------------------
+
+By default, the inclusive language check is applied only to |RST| files located
+under the documentation directory (usually :file:`docs`).
+To check Markdown files, for example, or to use a location other than the :file:`docs` sub-tree, you must override the ``ALLFILES`` variable in :file:`Makefile.sp` (see :ref:`Makefile`).
+
+You can find more information about available options in the `woke User Guide`_.
+
+Inclusive language check exemptions
+-----------------------------------
+
+Sometimes, you might need to use some non-inclusive words.
+In such cases, create check exemptions for them.
+
+See the `woke documentation`_ for how to do this.
+The following sections provide some examples.
+
+Exempt a word
+~~~~~~~~~~~~~
+
+To exempt an individual word, place a custom ``none`` role (defined in the ``canonical-sphinx-extensions`` Sphinx extension) anywhere on the line containing the word in question.
+The role syntax is::
+
+   :none:`wokeignore:rule=<SOME_WORD>,`
+
+For instance::
+
+   This is your text. The word in question is here: whitelist. More text. :none:`wokeignore:rule=whitelist,`
+
+To exempt an element of a URL, use the standard |RST| method of placing links at the bottom of the page (or in a separate file) and place a comment line immediately above the URL line.
+The comment syntax is::
+
+   .. wokeignore:rule=<SOME_WORD>
+
+Here is an example where a URL element contains the string "master": :none:`wokeignore:rule=master,`
+
+.. code-block:: none
+
+   .. LINKS
+   .. wokeignore:rule=master
+   .. _link definition: https://some-external-site.io/master/some-page.html
+
+You can now refer to the label ``link definition_`` in the body of the text.
+
+Exempt an entire file
+~~~~~~~~~~~~~~~~~~~~~
+
+A more drastic solution is to make an exemption for the contents of an entire file.
+For example, to exempt file :file:`docs/foo/bar.rst`, add the following line to the file :file:`.wokeignore`::
+
+   foo/bar.rst

sp-docs/docs/automatic_checks_links.rst

@@ -0,0 +1,18 @@
+.. _automatic-checks-links:
+
+Link check
+==========
+
+The link check uses Sphinx to access the links in the documentation output and validate whether they are working.
+
+Run the link check
+------------------
+
+Validate links within the documentation::
+
+   make linkcheck
+
+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 :file:`conf.py` file.

sp-docs/docs/automatic_checks_spelling.rst

@@ -0,0 +1,40 @@
+.. _automatic-checks-spelling:
+
+Spelling check
+==============
+
+The spelling check uses ``pyspelling`` to check the spelling in your documentation.
+It ignores code (both code blocks and inline code) and URLs (but it does check the link text).
+
+Run the spelling check
+----------------------
+
+Ensure there are no spelling errors in the documentation::
+
+  make spelling
+
+If you only want to check the existing output and do not want to build the HTML again, run the spelling check separately::
+
+  make spellcheck
+
+Configure the spelling check
+----------------------------
+
+The spelling check uses ``pyspelling``, which in turn relies on ``aspell``.
+Its configuration is located in the :file:`.sphinx/spellingcheck.yaml` file.
+
+The starter pack includes a common list of words that should be excluded from the check (:file:`.sphinx/.wordlist.txt`).
+You shouldn't edit this file, because it is maintained and updated centrally and contains words that apply across all projects.
+To add custom exceptions for your project, add them to the :file:`.custom_wordlist.txt` file.
+
+If you need to add systematic exceptions for specific HTML tags or CSS classes (for example, all image captions or H2 headings), you can do this in the :file:`.sphinx/spellingcheck.yaml` file.
+You can configure which HTML elements to exclude under ``pyspelling.filters.html``.
+
+Exclude specific terms
+----------------------
+
+Sometimes, you need to use a term in a specific context that should usually fail the spelling check.
+(For example, you might need to refer to a product called ``ABC Docs``, but you do not want to add ``docs`` to the word list because it isn't a valid word.)
+
+In this case, you can use the ``:spellexception:`` role.
+See `More useful markup`_ in the |RST| style guide (also available in MyST).

sp-docs/docs/automatic_checks_styleguide.rst

@@ -0,0 +1,60 @@
+.. _automatic-checks-styleguide:
+
+Style guide linting
+===================
+
+The starter pack includes a method to run the `Vale`_ documentation linter configured with `the Vale rules for the current style guide <Vale rules_>`_.
+
+
+Run the style guide linting
+---------------------------
+
+Check documentation with Vale::
+
+   make vale
+
+Vale can run against individual files, directories, or globs.
+To set a specific target::
+
+    make vale TARGET=example.file
+    make vale TARGET=example-directory
+
+.. note::
+
+    Running Vale against a directory will also run against subfolders.
+
+You can use wildcards to run against all files matching a string, or an extension.
+
+For example, to run against all :code:`.md` files within a folder::
+
+    make vale TARGET=*.md
+
+To match, for example, :code:`doc_1.md` and :code:`doc_2.md`::
+
+    make vale TARGET=doc*
+
+
+Exempt paragraphs
+-----------------
+
+To disable Vale linting within individual files, specific markup can be used.
+
+For Markdown:
+
+.. code-block:: Markdown
+
+   <!-- vale off -->
+
+   This text will be ignored by Vale.
+
+   <!-- vale on -->
+
+For |RST|:
+
+.. code-block:: rest
+
+   .. vale off
+
+   This text will be ignored by Vale.
+
+   .. vale on

sp-docs/docs/build.rst

@@ -0,0 +1,67 @@
+.. _build:
+
+Build and preview
+=================
+
+The starter pack provides make commands to build and view the documentation.
+All these commands will automatically set up the Python environment if it isn't set up yet.
+
+.. _build-docs:
+
+Build the documentation
+-----------------------
+
+To build the documentation, run the following command::
+
+  make html
+
+This command installs the required tools and renders the output to the :file:`_build/` directory in your documentation directory.
+
+.. important::
+   When you run :command:`make html` again, it updates the documentation for changed files only.
+
+   This speeds up the build, but it can cause you to miss warnings or errors that were displayed before.
+   To force a clean build, see :ref:`build-clean`.
+
+Make sure that the documentation builds without any warnings (warnings are treated as errors).
+
+.. _build-clean:
+
+Run a clean build
+-----------------
+
+To delete all existing output files and build all files again, run the following command::
+
+  make clean-doc html
+
+To delete both the existing output files and the Python environment and build the full documentation again, run the following command::
+
+  make clean html
+
+View the documentation
+----------------------
+
+To view the documentation output, run the following command::
+
+  make serve
+
+This command builds the documentation and serves it on :literalref:`http://127.0.0.1:8000/`.
+
+
+Live view
+---------
+
+Instead of building the documentation for each change and then serving it, you can run a live preview of the documentation::
+
+  make run
+
+This command builds the documentation and serves it on :literalref:`http://127.0.0.1:8000/`.
+When you change a documentation file and save it, the documentation will be automatically rebuilt and refreshed in the browser.
+
+.. important::
+   The :command:`run` target is very convenient while working on documentation updates.
+
+   However, it is quite error-prone because it displays warnings or errors only when they occur.
+   If you save other files later, you might miss these messages.
+
+   Therefore, you should always :ref:`build-clean` before finalising your changes.