diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml index cba712e5..2f3f64ab 100644 --- a/.github/workflows/automatic-doc-checks.yml +++ b/.github/workflows/automatic-doc-checks.yml @@ -1,9 +1,12 @@ name: Main Documentation Checks on: - - push - - pull_request - - workflow_dispatch + push: + pull_request: + paths: + - 'docs/**' + workflow_dispatch: + concurrency: group: ${{ github.workflow }}-${{ github.ref }} diff --git a/docs/.custom_wordlist.txt b/docs/.custom_wordlist.txt index d321a9b9..4beb4ad5 100644 --- a/docs/.custom_wordlist.txt +++ b/docs/.custom_wordlist.txt @@ -20,4 +20,5 @@ OpenStackApplication yaml backoff BACKOFF -websockets \ No newline at end of file +websockets +enablement \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile index 5a6f134b..876d2af4 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -77,10 +77,10 @@ serve: html clean: clean-doc @test ! -e "$(VENVDIR)" -o -d "$(VENVDIR)" -a "$(abspath $(VENVDIR))" != "$(VENVDIR)" rm -rf $(VENVDIR) - rm -rf .sphinx/.doctrees clean-doc: git clean -fx "$(BUILDDIR)" + rm -rf .sphinx/.doctrees spelling: html . $(VENV) ; python3 -m pyspelling -c .sphinx/spellingcheck.yaml @@ -93,7 +93,7 @@ woke: woke-install -c https://github.com/canonical/Inclusive-naming/raw/main/config.yml pa11y: pa11y-install html - find $(BUILDDIR) -name *.html -exec $(PA11Y) {} \; + find $(BUILDDIR) -name *.html -print0 | xargs -n 1 -0 $(PA11Y) # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/docs/help-woke.rst b/docs/help-woke.rst deleted file mode 100644 index 7ee332d3..00000000 --- a/docs/help-woke.rst +++ /dev/null @@ -1,59 +0,0 @@ -:orphan: - -=================================== -Inclusive language check exemptions -=================================== - -This page provides an overview of two inclusive language check exemption -methods for files written in reST format. See the `woke documentation`_ for -full coverage. - -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: - -.. code-block:: none - - :none:`wokeignore:rule=,` - -For instance: - -.. code-block:: none - - This is your text. The word in question is here: whitelist. More text. :none:`wokeignore:rule=whitelist,` - -To exempt an element of a URL, it is recommended to use the standard reST -method of placing links at the bottom of the page (or in a separate file). In -this case, a comment line is placed immediately above the URL line. The comment -syntax is: - -.. code-block:: none - - .. wokeignore:rule= - -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 ``docs/foo/bar.rst`` add the following line -to file ``.wokeignore``: - -.. code-block:: none - - foo/bar.rst - -.. LINKS -.. _woke documentation: https://docs.getwoke.tech/ignore diff --git a/docs/readme.rst b/docs/readme.rst index 8587ee19..bb1390e2 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -1,27 +1,85 @@ :orphan: +:hide-toc: Documentation starter pack ========================== -See the `Read the Docs at Canonical `_ and -`How to publish documentation on Read the Docs `_ guides for -instructions on how to get started with Sphinx documentation. +The Documentation starter pack contains tools and configuration options for +building a documentation site with Sphinx. Its main features include: + +* bundled Sphinx theme, configuration, and extensions +* build checks: links, spelling, inclusive language + +One strong point of the starter pack is its support for customisation that is +layered on top of a core configuration - this applies to all the above +features. There are also many other goodies included to enrich your doc set. + +Contents +-------- + +This README is divided into two main parts: enable the starter pack or work +with your documentation post-enablement. + +- `Enable the starter pack`_ + + * `Initialise your repository`_ + + + `Standalone documentation repository`_ + + `Documentation in a code repository`_ + + `Automation`_ + + * `Build the documentation`_ + * `Configure the documentation`_ + + + `Configure the header`_ + + `Activate/deactivate feedback button`_ + + `Configure included extensions`_ + + `Add custom configuration`_ -Then go through the following sections to use this starter pack to set up your docs repository. + * `Change log`_ + +- `Work with your documentation`_ + + * `Install prerequisite software`_ + * `View the documentation`_ + + * `Local checks`_ + + + `Local build`_ + + `Spelling check`_ + + `Inclusive language check`_ + + `Link check`_ + + * `Configure the spelling check`_ + * `Customisation of inclusive language checks`_ + * `Configure the link check`_ + * `Add redirects`_ + * `Other resources`_ + +Enable the starter pack +----------------------- + +This section is for repository administrators. It shows how to initialise a +repository with the starter pack. Once this is done, documentation contributors +should follow section `Work with your documentation`_. **Note:** After setting up your repository with the starter pack, you need to track the changes made to it and manually update your repository with the required files. The `change log `_ lists the most relevant (and of course all breaking) changes. We're planning to provide the contents of this repository as an installable package in the future to make updates easier. -Set up your documentation repository ------------------------------------- +See the `Read the Docs at Canonical `_ and +`How to publish documentation on Read the Docs `_ guides for +instructions on how to get started with Sphinx documentation. + +Initialise your 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. +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. The next two sections show the steps needed for each scenario. -The next two sections provide manual steps for enabling the starter pack for your repository. See `Setup script `_ for an automated method (currently in beta). +See the `Automation`_ section if you would like to have this done via a shell script. Standalone documentation repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To create a standalone documentation repository, clone this starter pack repository, `update the configuration <#configure-the-documentation>`_, and @@ -47,7 +105,7 @@ Here is one way to do this for newly-created fictional docs repository git push -f upstream main Documentation in a code repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To add documentation to an existing code repository: @@ -67,8 +125,119 @@ To add documentation to an existing code repository: ``.readthedocs.yaml``" (under **Advanced Settings**) will need to be given the value of ``docs/.readthedocs.yaml``. -Getting started ---------------- +Automation +^^^^^^^^^^ + +To automate the initialisation for either scenario ensure you have the following: + +- A GitHub repository where you want to host your documentation, cloned to your local machine. The recommended approach is to host the documentation alongside your code in a ``docs`` folder. But a standalone documentation repository is also an option; in this case, start with an empty repository. +- Git and Bash installed on your system. + +There is a provided ``init.sh`` Bash script that does the following: + +- clones the starter pack GitHub repository +- creates the specified installation directory if necessary +- updates working directory paths in workflow files, and updates configuration paths in the ``.readthedocs.yaml`` file +- copies and moves contents and ``.github`` files from the starter pack to the installation directory +- deletes the cloned repository when it's done + +To use the script: + +#. copy ``init.sh`` to your repository's root directory +#. run the script: ``./init.sh`` +#. enter the installation directory when prompted. For standalone repositories, enter ".". For documentation alongside code, enter the folder where your documentation is (e.g. ``docs``) + +When the script completes, review all changes before committing them. + +Build the documentation +~~~~~~~~~~~~~~~~~~~~~~~ + +The documentation needs to be built in order to be published. This is explained +in more detail in section `Local checks`_ (for contributors), but at this time +you should verify a successful build. Run the following commands from where +your doc files were placed (repository root or the ``docs`` directory): + +.. code-block:: none + + make install + make html + +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. + +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``. + +Configure included extensions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The starter pack includes a set of extensions that are useful for all documentation sets. +They are pre-configured as needed, but you can customise their configuration in the ``custom_conf.py`` file. + +The following extensions are always included: + +- |sphinx-design|_ +- |sphinx_tabs.tabs|_ +- |sphinx_reredirects|_ +- |lxd-sphinx-extensions|_ (``youtube-links``, ``related-links``, ``custom-rst-roles``, and ``terminal-output``) +- |sphinx_copybutton|_ +- |sphinxext.opengraph|_ +- |myst_parser|_ +- |sphinxcontrib.jquery|_ +- |notfound.extension|_ + +You can add further extensions in the ``custom_extensions`` variable in ``custom_conf.py``. + +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. + +The following links can help you with additional configuration: + +- `Sphinx configuration`_ +- `Sphinx extensions`_ +- `Furo documentation`_ (Furo is the Sphinx theme we use as our base.) + +Change log +~~~~~~~~~~ + +See the `change log `_ for a list of relevant changes to the starter pack. + +Work with your documentation +---------------------------- + +This section is for documentation contributors. It assumes that the current +repository has been initialised with the starter pack as described in +section `Enable the starter pack`_. There are make targets defined in the ``Makefile`` that do various things. To get started, we will: @@ -159,25 +328,6 @@ Validate links within the documentation: 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -196,80 +346,82 @@ for example, or to use a location other than the ``docs`` sub-tree, you must change how the ``woke`` tool is invoked from within ``docs/Makefile`` (see the `woke User Guide `_ for help). +Inclusive language check exemptions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + Some circumstances may require you to use some non-inclusive words. In such -cases you will need to create check-exemptions for them. See file -:doc:`help-woke` for how to do that. +cases you will need to create check-exemptions for them. -Configure the link check -~~~~~~~~~~~~~~~~~~~~~~~~ +This page provides an overview of two inclusive language check exemption +methods for files written in reST format. See the `woke documentation`_ for +full coverage. -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. +Exempt a word +............. -Activate/deactivate feedback button -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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: -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. +.. code-block:: none -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``. + :none:`wokeignore:rule=,` -Add redirects -~~~~~~~~~~~~~ +For instance: -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. +.. code-block:: none -Configure included extensions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + This is your text. The word in question is here: whitelist. More text. :none:`wokeignore:rule=whitelist,` -The starter pack includes a set of extensions that are useful for all documentation sets. -They are pre-configured as needed, but you can customise their configuration in the ``custom_conf.py`` file. +To exempt an element of a URL, it is recommended to use the standard reST +method of placing links at the bottom of the page (or in a separate file). In +this case, a comment line is placed immediately above the URL line. The comment +syntax is: -The following extensions are always included: +.. code-block:: none -- |sphinx-design|_ -- |sphinx_tabs.tabs|_ -- |sphinx_reredirects|_ -- |lxd-sphinx-extensions|_ (``youtube-links``, ``related-links``, ``custom-rst-roles``, and ``terminal-output``) -- |sphinx_copybutton|_ -- |sphinxext.opengraph|_ -- |myst_parser|_ -- |sphinxcontrib.jquery|_ -- |notfound.extension|_ + .. wokeignore:rule= -You can add further extensions in the ``custom_extensions`` variable in ``custom_conf.py``. +Here is an example where a URL element contains the string "master": :none:`wokeignore:rule=master,` -Add custom configuration +.. 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 ``docs/foo/bar.rst`` add the following line +to file ``.wokeignore``: + +.. code-block:: none + + foo/bar.rst + +Configure the link check ~~~~~~~~~~~~~~~~~~~~~~~~ -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. +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. -The following links can help you with additional configuration: +Add redirects +~~~~~~~~~~~~~ -- `Sphinx configuration`_ -- `Sphinx extensions`_ -- `Furo documentation`_ (Furo is the Sphinx theme we use as our base.) +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. Other resources ---------------- +~~~~~~~~~~~~~~~ - `Example product documentation `_ - `Example product documentation repository `_ -Change log ----------- - -See the `change log `_ for a list of relevant changes to the starter pack. - .. LINKS .. wokeignore:rule=master @@ -296,3 +448,5 @@ See the `change log