From 1cb2780970f8a791ce1aa79e36ca1efc88d7a8ac Mon Sep 17 00:00:00 2001 From: Ruth Fuchss Date: Mon, 8 Jul 2024 19:11:13 +0200 Subject: [PATCH 1/4] doc: update the starter pack documentation Signed-off-by: Ruth Fuchss --- sp-docs/.custom_wordlist.txt | 1 + sp-docs/docs/automatic_checks.rst | 29 ++ .../docs/automatic_checks_accessibility.rst | 42 +++ .../automatic_checks_inclusivelanguage.rst | 79 +++++ sp-docs/docs/automatic_checks_links.rst | 18 ++ sp-docs/docs/automatic_checks_spelling.rst | 40 +++ sp-docs/docs/automatic_checks_styleguide.rst | 60 ++++ sp-docs/docs/build.rst | 67 ++++ sp-docs/docs/customise.rst | 145 +++++++++ sp-docs/docs/enable.rst | 265 +++------------- sp-docs/docs/examples.rst | 18 ++ sp-docs/docs/guidance.rst | 28 ++ sp-docs/docs/makefile.rst | 21 ++ sp-docs/docs/prereqs.rst | 37 +++ sp-docs/docs/quickstart.rst | 78 +++-- sp-docs/docs/rtd.rst | 42 +++ sp-docs/docs/setup.rst | 24 ++ sp-docs/docs/update.rst | 15 + sp-docs/docs/work.rst | 296 ------------------ sp-docs/index.rst | 30 +- sp-docs/reuse/links.txt | 46 ++- 21 files changed, 782 insertions(+), 599 deletions(-) create mode 100644 sp-docs/docs/automatic_checks.rst create mode 100644 sp-docs/docs/automatic_checks_accessibility.rst create mode 100644 sp-docs/docs/automatic_checks_inclusivelanguage.rst create mode 100644 sp-docs/docs/automatic_checks_links.rst create mode 100644 sp-docs/docs/automatic_checks_spelling.rst create mode 100644 sp-docs/docs/automatic_checks_styleguide.rst create mode 100644 sp-docs/docs/build.rst create mode 100644 sp-docs/docs/customise.rst create mode 100644 sp-docs/docs/examples.rst create mode 100644 sp-docs/docs/guidance.rst create mode 100644 sp-docs/docs/makefile.rst create mode 100644 sp-docs/docs/prereqs.rst create mode 100644 sp-docs/docs/rtd.rst create mode 100644 sp-docs/docs/setup.rst create mode 100644 sp-docs/docs/update.rst delete mode 100644 sp-docs/docs/work.rst diff --git a/sp-docs/.custom_wordlist.txt b/sp-docs/.custom_wordlist.txt index e69de29b..569b15a0 100644 --- a/sp-docs/.custom_wordlist.txt +++ b/sp-docs/.custom_wordlist.txt @@ -0,0 +1 @@ +WCAG diff --git a/sp-docs/docs/automatic_checks.rst b/sp-docs/docs/automatic_checks.rst new file mode 100644 index 00000000..2af3a329 --- /dev/null +++ b/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 diff --git a/sp-docs/docs/automatic_checks_accessibility.rst b/sp-docs/docs/automatic_checks_accessibility.rst new file mode 100644 index 00000000..14012dff --- /dev/null +++ b/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 `_ on GitHub. diff --git a/sp-docs/docs/automatic_checks_inclusivelanguage.rst b/sp-docs/docs/automatic_checks_inclusivelanguage.rst new file mode 100644 index 00000000..15270bef --- /dev/null +++ b/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=,` + +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= + +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 diff --git a/sp-docs/docs/automatic_checks_links.rst b/sp-docs/docs/automatic_checks_links.rst new file mode 100644 index 00000000..9b1913c4 --- /dev/null +++ b/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. diff --git a/sp-docs/docs/automatic_checks_spelling.rst b/sp-docs/docs/automatic_checks_spelling.rst new file mode 100644 index 00000000..8e16ced4 --- /dev/null +++ b/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). diff --git a/sp-docs/docs/automatic_checks_styleguide.rst b/sp-docs/docs/automatic_checks_styleguide.rst new file mode 100644 index 00000000..b246982a --- /dev/null +++ b/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 `_. + + +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 + + + + This text will be ignored by Vale. + + + +For |RST|: + +.. code-block:: rest + + .. vale off + + This text will be ignored by Vale. + + .. vale on diff --git a/sp-docs/docs/build.rst b/sp-docs/docs/build.rst new file mode 100644 index 00000000..ccd1cc7a --- /dev/null +++ b/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. diff --git a/sp-docs/docs/customise.rst b/sp-docs/docs/customise.rst new file mode 100644 index 00000000..37aa3676 --- /dev/null +++ b/sp-docs/docs/customise.rst @@ -0,0 +1,145 @@ +.. _customise: + +Customise the setup +=================== + +The starter pack is configured in a way that makes sense for most projects. +However, you must customise some settings for your project, like the project name. + +In addition, there are some settings that you can customise if you wish so. +And of course, you can add your own configuration as well. + +Required customisation +---------------------- + +You must check and update some of the configuration to adapt the documentation to your project. + +Update the project information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Edit the :file:`conf.py` file and update the configuration in the ``Project information`` section. +See the comments in the file for more information about each setting. + +You can adapt settings in the rest of the file as well, but this isn't required. + +Open Graph configuration +^^^^^^^^^^^^^^^^^^^^^^^^ + +When you post a link to your documentation somewhere (for example, on Mattermost or Discourse), it might be shown with a preview. +This preview is configured through `Open Graph`_. + +If you don't know yet where your documentation will be hosted, you can leave the URL empty. +If you do, specify the hosting URL. +You can leave the defaults for the website name and the preview image or specify your own. + +Configure the header +~~~~~~~~~~~~~~~~~~~~ + +By default, the header contains your product tag, product name (taken from the ``project`` setting in the :file:`conf.py` file), a link to your product page, and a drop-down menu for "More resources". + +In many cases, this default setup is sufficient, but you should always check it. + +You can change any of those links or add further links to the "More resources" drop-down by editing the :file:`.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. + +Optional customisation +---------------------- + +The starter pack contains several features that you can configure, or turn off if they aren't suitable for your documentation. + +Deactivate the feedback button +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the starter pack includes a feedback button at the top of each page in the documentation. +This button 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 :file:`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 :file:`conf.py` file to ``True``. + +Configure the contributor display +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, the starter pack will display a list of contributors at the bottom of each page. +This requires the GitHub URL and folder to be configured. + +If you want to turn this contributor listing off, you can do so by setting the ``display_contributors`` variable in the :file:`conf.py` file to ``False``. + +To configure that only recent contributors are displayed, you can set the ``display_contributors_since`` variable. +It takes any Linux date format (for example, a full date, or an expression like "3 months"). + +Add redirects +~~~~~~~~~~~~~ + +If you rename a source file, its URL will change. +To prevent broken links, you should add a redirect from the old URL to the new URL in this case. + +You can add redirects in the ``redirects`` variable in the :file:`conf.py` file. + +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 :file:`conf.py` file. + +The following extensions are always included: + +- :literalref:`sphinx-design ` +- :literalref:`sphinx_copybutton ` +- :literalref:`sphinxcontrib.jquery ` + +The following extensions are included unless they are disabled when loading the extension: + +- :literalref:`sphinx_tabs.tabs ` +- :literalref:`sphinx_reredirects ` +- :literalref:`sphinxext.opengraph ` +- :literalref:`canonical-sphinx-extensions ` (``youtube-links``, ``related-links``, ``custom-rst-roles``, and ``terminal-output``) +- :literalref:`myst_parser ` +- :literalref:`notfound.extension ` + +You can add further extensions in the ``extensions`` variable in :file:`conf.py`. +If the extensions need specific Python packages, add those to the :file:`requirements.py` file. + +Add page-specific configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can override some global configuration for specific pages. + +For example, you can configure whether to display Previous/Next buttons at the bottom of pages by setting the ``sequential_nav`` variable in the :file:`conf.py` file. +You can then override this default setting for a specific page (for example, to turn off the Previous/Next buttons by default, but display them in a multi-page tutorial). + +To do so, add `file-wide metadata`_ at the top of a page. +See the following examples for how to enable Previous/Next buttons for one page: + +|RST|:: + + :sequential_nav: both + + [Page contents] + +MyST:: + + --- + sequential_nav: both + --- + + [Page contents] + +Possible values for the ``sequential_nav`` field are ``none``, ``prev``, ``next``, and ``both``. +See the :file:`conf.py` file for more information. + +Another example for page-specific configuration is the ``hide-toc`` field (provided by `Furo `_), which can be used to hide the page-internal table of content. +See `Hiding Contents sidebar`_. + +Add your own configuration +-------------------------- + +To add custom configuration for your project, see the ``Additions to default configuration`` and ``Additional configuration`` sections in the :file:`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) + +If you need additional Python packages for any custom processing you do in your documentation, add them to the :file:`.sphinx/requirements.txt` file. diff --git a/sp-docs/docs/enable.rst b/sp-docs/docs/enable.rst index 1c576c0e..7beb157c 100644 --- a/sp-docs/docs/enable.rst +++ b/sp-docs/docs/enable.rst @@ -1,247 +1,62 @@ .. _enable: 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 :ref:`work`. +You can use the starter pack to set up your documentation in one of the following ways: -**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. +- As a standalone documentation project in a new repository +- In a dedicated documentation folder in an existing code 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. +The starter pack provides a shell script that updates and copies the starter pack files to the selected location. -Initialise your repository -~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: + The recommended way of setting up the starter pack is to use the initialisation script. + This method is automatically tested for the two scenarios mentioned above. -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. + However, if you prefer to copy the files manually instead of running the script, this is also possible. + Make sure to check the comments in the script in this case, because you will need to update the configuration in several files (in addition to copying the files to the correct locations). + Also see :ref:`enable-behind-the-scenes`. -See the `Automation`_ section if you would like to have this done via a shell script. -Standalone documentation repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Run the initialisation script +----------------------------- -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. +The initialisation script will download all required files, update them, and copy them to the selected location. -You don't need to move any files, and you don't need to do any special -configuration on Read the Docs. +1. Download :file:`init.sh` from the starter pack repository: :literalref:`https://raw.githubusercontent.com/canonical/sphinx-docs-starter-pack/use-canonical-sphinx-extension/init.sh` +#. Put the script into the root folder of the Git repository in which you want to enable the starter pack. -Here is one way to do this for newly-created fictional docs repository -``canonical/alpha-docs``: + This can be a new, empty repository or your code repository. +#. Make the script executable:: -.. code-block:: none + chmod u+x init.sh +#. Run the script:: - 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 + ./init.sh +#. When prompted, enter the installation directory: -Documentation in a code repository -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + - For standalone repositories, enter a full stop (``.``). + - For documentation in code repositories, enter the name of the documentation folder (for example, ``docs``). -To add documentation to an existing code repository: + If the folder does not yet exist, it is created. + If the folder exists already, some of its files might be overwritten by starter pack files, so make sure you have a backup. +#. Check the output for any warnings or errors. -#. Create a directory called :file:`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 :file:`.git` directory). -#. Copy the file(s) located in the :file:`docs/.github/workflows` directory into - the :file:`.github/workflows` directory in the root of the code repository. -#. In the above workflow file(s), change the value of the - :file:`working-directory` field from ``.`` to ``docs``. -#. Create a symbolic link to the :file:`docs/.wokeignore` file from the root - directory of the code repository. -#. In the :file:`docs/.readthedocs.yaml` file, set the following: +You can now delete the :file:`init.sh` file. - * ``post_checkout: cd docs && python3 .sphinx/build_requirements.py`` - * ``configuration: docs/conf.py`` - * ``requirements: docs/.sphinx/requirements.txt`` +.. _enable-behind-the-scenes: -**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``. +Behind the scenes +----------------- -Automation -^^^^^^^^^^ +We recommend using the initialisation script to enable the starter pack. +Here's a summary of what it does: -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 :file:`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 :file:`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 :file:`.readthedocs.yaml` file. -- Copies and moves contents and :file:`.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 before publication. This is explained -in more detail in section :ref:`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_copybutton|_ -- |sphinxcontrib.jquery|_ - -The following extensions will automatically be included based on the configuration in the ``custom_conf.py`` file: - -- |sphinx_tabs.tabs|_ -- |sphinx_reredirects|_ -- |sphinxext.opengraph|_ -- |lxd-sphinx-extensions|_ (``youtube-links``, ``related-links``, ``custom-rst-roles``, and ``terminal-output``) -- |myst_parser|_ -- |notfound.extension|_ - -You can add further extensions in the ``custom_extensions`` variable in ``custom_conf.py``. -If the extensions need specific Python packages, add those to the ``custom_required_modules`` variable. - -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.) - -Add Python packages -^^^^^^^^^^^^^^^^^^^ - -If you need additional Python packages for any custom processing you do in your documentation, add them to the ``custom_required_modules`` variable in ``custom_conf.py``. - -If you use these packages inside of ``custom_conf.py``, you will encounter a circular dependency (see issue `#197`_). -To work around this problem, add a step that installs the packages to the ``.readthedocs.yaml`` file: - -.. code-block:: yaml - - ... - jobs: - pre_install: - - pip install - - python3 .sphinx/build_requirements.py - ... - -In addition, override the ``ADDPREREQS`` variable in the Makefile with the names of the packages. -For example:: - - make html ADDPREREQS='' - - -Add page-specific configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You can override some global configuration for specific pages. - -For example, you can configure whether to display Previous/Next buttons at the bottom of pages in the ``custom_conf.py`` file. -You can then override this default setting for a specific page (for example, to turn off the Previous/Next buttons by default, but display them in a multi-page tutorial). - -To do so, add `file-wide metadata`_ at the top of a page. -See the following examples for how to enable Previous/Next buttons for one page: - -reST - .. code-block:: - - :sequential_nav: both - - [Page contents] - -MyST - .. code-block:: - - --- - sequential_nav: both - --- - - [Page contents] - -Possible values for the ``sequential_nav`` field are ``none``, ``prev``, ``next``, and ``both``. -See the ``custom_conf.py`` file for more information. - -Another example for page-specific configuration is the ``hide-toc`` field (provided by `Furo `_), which can be used to hide the page-internal table of content. -See `Hiding Contents sidebar`_. - -Change log -~~~~~~~~~~ - -See the `change log `_ for a list of relevant changes to the starter pack. +1. Prompt for the directory that will contain the documentation. +#. Clone the starter pack repository into a temporary directory. +#. Update several of the configuration files to adapt paths to the documentation directory. +#. Create the documentation directory. +#. Copy the starter pack files into the documentation directory. +#. Move some required files into the root folder of the repository (the GitHub workflow file and a :file:`.wokeignore` file), unless they exist already. +#. Remove the temporary directory. diff --git a/sp-docs/docs/examples.rst b/sp-docs/docs/examples.rst new file mode 100644 index 00000000..5ef51e05 --- /dev/null +++ b/sp-docs/docs/examples.rst @@ -0,0 +1,18 @@ +.. _examples: + +Starter pack examples +===================== + +The following documentation sets use the starter pack and can serve as implementation examples. + +If you are using the starter pack, feel free to open a PR against this page and add your project! + +.. list-table:: + :header-rows: 1 + + * - Documentation + - Using the extension? + * - `LXD `_ + - No + * - `MicroCloud `_ + - No diff --git a/sp-docs/docs/guidance.rst b/sp-docs/docs/guidance.rst new file mode 100644 index 00000000..d4b2ced0 --- /dev/null +++ b/sp-docs/docs/guidance.rst @@ -0,0 +1,28 @@ +.. _guidance: + +Get guidance +============ + +The starter pack uses `Sphinx`_ as the documentation framework. +It supports markup in both `reStructuredText`_ and `Markdown`_ with `MyST`_. + +It's outside of the scope of the starter pack to teach you how to use these tools to create documentation, but you can check the :ref:`quickstart` for a very brief introduction. +For more detailed information and syntax guides, see the linked documents. + +To make it easier for you to get started, and to keep our documentation consistent, the following style guides give recommendations and conventions for using |RST| and Markdown/MyST: + +- `reStructuredText style guide`_ +- `MyST style guide`_ + +The starter pack also contains cheat sheets for both markup languages that allow to easily copy and paste the markup that you want. +See the :file:`doc-cheat-sheet.rst` and :file:`doc-cheat-sheet-myst.md` files. + +Other resources +--------------- + +Canonical documentation uses `Diátaxis`_. + +The following documentation repository contains an example for how to implement this structure: + +- `Example product documentation `_ +- `Example product documentation repository `_ diff --git a/sp-docs/docs/makefile.rst b/sp-docs/docs/makefile.rst new file mode 100644 index 00000000..4555e075 --- /dev/null +++ b/sp-docs/docs/makefile.rst @@ -0,0 +1,21 @@ +.. _makefile: + +Integrate the Makefiles +======================= + +The starter pack contains two Makefiles: :file:`Makefile` and :file:`Makefile.sp`. + +:file:`Makefile.sp` implements the targets provided by the starter pack. +You should keep it up-to-date with recent changes to the starter pack; therefore, avoid doing updates to the file. +(If you need updates, consider contributing them to the starter pack!) + +You can use :file:`Makefile` to add custom targets or different target names. + +If you want to integrate the starter pack targets into the main Makefile of your project, you can do so with a command similar to the following:: + + doc-%: + cd docs && $(MAKE) -f Makefile.sp sp-$* ALLFILES='*.md **/*.md' + +This example will create targets prefixed with ``doc-`` (for example, ``doc-html`` and ``doc-serve``). +When calling these targets, they switch to the documentation folder (``docs`` in this case) and run the corresponding ``sp-*`` targets from :file:`Makefile.sp`. +In addition, the ``ALLFILES`` variable is overridden with a different set of files (this is needed for the :ref:`automatic-checks-inclusivelanguage`). diff --git a/sp-docs/docs/prereqs.rst b/sp-docs/docs/prereqs.rst new file mode 100644 index 00000000..c41bb49b --- /dev/null +++ b/sp-docs/docs/prereqs.rst @@ -0,0 +1,37 @@ +.. _prereqs: + +Install prerequisites +===================== + +The documentation framework that the starter pack uses bundles most prerequisites in a Python virtual environment, so you don't need to worry about installing them. +There are only a few packages that you need to install on your host system. + +Install prerequisite software +----------------------------- + +Before you start, make sure that you have ``make``, ``python3``, ``python3-venv``, and ``python3-pip`` on your system:: + + sudo apt update + sudo apt install make python3 python3-venv python3-pip + +Python environment +------------------ + +The Python prerequisites from the :file:`.sphinx/requirements.txt` file are automatically installed when you build the documentation. + +If you want to install them manually, you can run the following command:: + + make install + +This command creates a virtual environment (:file:`.sphinx/venv`) and installs dependency software within it. + +If you want to remove the installed Python packages (for example, to enforce a re-installation), run the following command:: + + make clean + +.. 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 to use a tool like Renovate to automatically update the requirements. + + - If you encounter the error ``locale.Error: unsupported locale setting`` when activating the Python virtual environment, include the environment variable in the command and try again: ``LC_ALL=en_US.UTF-8 make run`` diff --git a/sp-docs/docs/quickstart.rst b/sp-docs/docs/quickstart.rst index 814a644a..833399ff 100644 --- a/sp-docs/docs/quickstart.rst +++ b/sp-docs/docs/quickstart.rst @@ -1,55 +1,65 @@ +.. _quickstart: + Quickstart guide ---------------- -An initial set of documentation can be built directly from a clone of this -repository. +The following steps will guide you through setting up your documentation using the starter pack and building an initial set of documentation. + +For more detailed information, see the other sections of the starter pack documentation. + +1. Download the :literalref:`init.sh` file from the starter pack repository and place it into the directory where you want to set up your documentation. + +#. Run the script and specify where you want the files for the documentation framework to be placed (either in the current directory or in a sub-directory). + Your own documentation files will need to be placed in the same directory (or sub-directories of it) later. + + See :ref:`enable` for detailed information on what the script does. + +#. Enter the documentation folder (the folder you specified when running the script) and build the documentation with the following command:: + + make run + + This command creates a virtual environment, installs the Python dependencies, builds the documentation, and serves it on :literalref:`http://127.0.0.1:8000/`. -First, clone this repository to a local directory, and change to this -directory: + See :ref:`build` for detailed information on different commands for building and viewing the documentation. -.. code-block:: sh +#. Keep this session running to rebuild the documentation automatically whenever a file is saved, and open :literalref:`http://127.0.0.1:8000/` in a web browser to see the locally built and hosted HTML. - git clone git@github.com:canonical/sphinx-docs-starter-pack - cd +#. To add a new page to the documentation, create a new document called :file:`reference.rst`, insert the following |RST|-formatted ``Reference`` heading, and then save the file: -Now build the documentation with the following command. This will create a virtual -environment, install the software dependencies, and build the documentation: + .. code-block:: rest -.. code-block:: sh + Reference + ========= - make run + .. note:: + This Quickstart guide uses |RST|, but if you prefer to use Markdown, you can create a :file:`reference.md` file with the following content instead: -Keep this session running to rebuild the documentation automatically whenever a -file is saved, and open |http://127.0.0.1:8000|_ in a web browser to see the -locally built and hosted HTML. + .. code-block:: Markdown -To add a new page to the documentation, create a new document called -``reference.rst`` in a text editor and insert the following reST-formatted -``Reference`` heading: + # Reference -.. code-block:: rest +#. Open :file:`index.rst`. - Reference - ========= + At the bottom of this file, add a 3-space-indented line containing ``Reference `` to the end of the ``toctree`` section, and then save the file. + This is the navigation title for the new document and its filename without the extension. -Now save ``reference.rst`` and open ``index.rst``. + The ``toctree`` section will now look like this: -At the bottom of this file, add an indented line containing ``Reference -`` to the end of the ``toctree`` section. This is the navigation -title for the new document and its filename without the ``.rst`` extension. + .. code-block:: rest -The ``toctree`` section will now look like this: + .. toctree:: + :hidden: + :maxdepth: 2 -.. code-block:: rest + self + Reference - .. toctree:: - :hidden: - :maxdepth: 2 + .. note:: + You can leave out the navigation title to use the document title instead. + This means that in this example, you could also just type ``reference`` instead of ``Reference ``. - ReadMe - Reference +#. Check :literalref:`http://127.0.0.1:8000/`. -Save ``index.rst`` and reload |http://127.0.0.1:8000|_. + The documentation will now show **Reference** added to the navigation, and selecting the link in the navigation will open the new ``reference.rst`` document. -The documentation will now show **Reference** added to the navigation and -selecting this will open the new ``reference.rst`` document. +See :ref:`guidance` for links to more detailed information about |RST| and Markdown/MyST. diff --git a/sp-docs/docs/rtd.rst b/sp-docs/docs/rtd.rst new file mode 100644 index 00000000..984920e6 --- /dev/null +++ b/sp-docs/docs/rtd.rst @@ -0,0 +1,42 @@ +.. _rtd: + +Set up Read the Docs +==================== + +For Canonical-specific information on how to set up your documentation on Read the Docs, see the `Read the Docs at Canonical `_ and `How to publish documentation on Read the Docs `_ guides. + +In general, after enabling the starter pack for your documentation, follow these steps to build and publish your documentation on Read the Docs: + +1. Make sure your documentation :ref:`builds without errors or warnings `. +#. Log into Read the Docs. +#. Use the `manual import`_ to create a project. +#. If your documentation is not on the root level but in a documentation folder, you must specify the path to the :file:`.readthedocs.yaml` file for your build. + You do this by navigating to :guilabel:`Admin` > :guilabel:`Settings` and specifying the path under "Path for ``.readthedocs.yaml``". + +After this initial setup, your documentation should build successfully. +If you get any errors, check the build log for indications on what the problem is. + +Configure the webhook +--------------------- + +If you have administrator privileges for the GitHub repository that you are adding, the integration webhook (which is responsible for automatically building the documentation when the repository changes) is created automatically. + +If you don't have administrator privileges, the webhook must be set up by someone who does. +See `How to manually configure a Git repository integration`_ if you want to set it up manually. + +Make your documentation public +------------------------------ + +By default, Read the Docs publishes your documentation for logged-in users only. + +To make the documentation public, you must configure the privacy level for each version of the documentation separately. +You can do this by navigating to the :guilabel:`Versions` tab and changing the :guilabel:`Privacy Level` for each version. + +Enable PR previews +------------------ + +To make Read the Docs automatically build your documentation when a pull request is opened or updated on GitHub, enable PR reviews for your project. + +To do so, navigate to :guilabel:`Admin` > :guilabel:`Settings` and select :guilabel:`Build pull requests for this project`. + +Read the Docs will then automatically build the documentation for each pull request, and the link to the output will be available as one of the checks in the pull request. diff --git a/sp-docs/docs/setup.rst b/sp-docs/docs/setup.rst new file mode 100644 index 00000000..a8e8534f --- /dev/null +++ b/sp-docs/docs/setup.rst @@ -0,0 +1,24 @@ +.. _setup: + +Initial setup +============= + +This section is intended for repository administrators. +It shows how to initially set up your documentation using the starter pack. +After this is done, documentation contributors can follow the instructions in :ref:`update`. + +.. important:: + After setting up your repository with the starter pack, you should track the changes made to the starter pack. + + Changes to the look and feel, as well as common functionality, will be automatically available through updates to the `Canonical Sphinx`_ extension. + + Changes to files that are part of the starter pack, for example, :ref:`automatic-checks`, might require you to manually update your repository with the required files. + See the starter pack's `change log`_ for the most relevant (and of course all breaking) changes. + +.. toctree:: + :maxdepth: 1 + + /docs/enable + /docs/customise + /docs/makefile + /docs/rtd diff --git a/sp-docs/docs/update.rst b/sp-docs/docs/update.rst new file mode 100644 index 00000000..84924573 --- /dev/null +++ b/sp-docs/docs/update.rst @@ -0,0 +1,15 @@ +.. _update: + +Update the documentation +======================== + +This section is intended for documentation contributors and covers how to work with the documentation after the repository has been set up with the starter pack as described in :ref:`enable`. + +You'll find information on how to build and preview the documentation, and some pointers on what you need to know about the documentation framework and where to get help with it. + +.. toctree:: + :maxdepth: 1 + + /docs/prereqs + /docs/build + /docs/guidance diff --git a/sp-docs/docs/work.rst b/sp-docs/docs/work.rst deleted file mode 100644 index da427a38..00000000 --- a/sp-docs/docs/work.rst +++ /dev/null @@ -1,296 +0,0 @@ -.. _work: - -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 -:ref:`enable`. - -There are make targets defined in the :file:`Makefile` that provide different functionality. To -get started, we will: - -* install prerequisite software -* view the documentation - -Install prerequisite software -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Before you start, make sure you have ``make``, ``python3``, ``python3-venv``, -and ``python3-pip`` on your system: - -.. code-block:: none - - sudo apt update - sudo apt install make python3 python3-venv python3-pip - -Some `validation tools <#local-checks>`_ won't be available by default. To -install them, you need ``snap`` and ``npm``: - -.. code-block:: none - - sudo apt install npm snapd - -To install the core prerequisites: - -.. code-block:: none - - make install - -This will create the required software list (``.sphinx/requirements.txt``), -which is used to create a virtual environment (``.sphinx/venv``) and install -dependency software within it. - -To install the validation tools: - -.. code-block:: none - - make woke-install - make pa11y-install - -You can add further Python modules to the required software list -(``.sphinx/requirements.txt``) in the ``custom_required_modules`` variable -in the ``custom_conf.py`` file. - -**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 perform several actions: - -* 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. - -.. note:: - - If you encounter the error ``locale.Error: unsupported locale setting`` when activating the Python virtual environment, include the environment variable in the command and try again: ``LC_ALL=en_US.UTF-8 make run`` - -.. _local-checks: - -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 - -If you only want to check the existing output and do not want to build the HTML again, run the spelling check separately: - -.. code-block:: shell - - make spellcheck - -Inclusive language check -^^^^^^^^^^^^^^^^^^^^^^^^ - -Ensure the documentation uses inclusive language: - -.. code-block:: shell - - make woke - -Accessibility check -^^^^^^^^^^^^^^^^^^^ - -Look for accessibility issues in rendered documentation: - -.. code-block:: shell - - make pa11y - -Link check -^^^^^^^^^^ - -Validate links within the documentation: - -.. code-block:: shell - - make linkcheck - -Style guide linting -^^^^^^^^^^^^^^^^^^^ - -Check documentation against the `Vale documentation linter configured with the current style guide `_. - -.. code-block:: shell - - make vale - -Vale can run against individual files, directories, or globs. To set a specific target: - -.. code-block:: shell - - make vale TARGET=example.file - make vale TARGET=example-directory - -.. note:: - - Running Vale against a directory will also run against subfolders. - -To run against all files with a specific extension within a folder: - -.. code-block:: shell - - make vale TARGET=*.md - -.. note:: - - Wildcards can be used to run against all files matching a string, or an extension. The example above will match against all :code:`.md` - files, and :code:`TARGET=doc*` will match both :code:`doc_1.md` and :code:`doc_2.md`. - -To disable Vale linting within individual files, specific markup can be used. - -For Markdown: - -.. code-block:: - - - - This text will be ignored by Vale. - - - -For reStructuredText: - -.. code-block:: - - .. vale off - - This text will be ignored by Vale. - - .. vale on - -Configure the spelling check -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The spelling check uses ``aspell``. -Its configuration is located in the ``.sphinx/spellingcheck.yaml`` file. - -To add exceptions for words flagged by the spelling check, edit the ``.custom_wordlist.txt`` file. -You shouldn't edit ``.sphinx/.wordlist.txt``, because this file is maintained and updated centrally and contains words that apply across all projects. - -Configure the inclusive language check -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, the inclusive language check is applied only to reST files located -under the documentation directory (usually ``docs``). To check Markdown files, -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. - -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 - -Configure the accessibility check -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The ``pa11y.json`` file at the starter pack root provides basic defaults; to -browse the available settings and options, see ``pa11y``'s `README -`_ on GitHub. - - -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. - -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. - -Other resources -~~~~~~~~~~~~~~~ - -- `Example product documentation `_ -- `Example product documentation repository `_ diff --git a/sp-docs/index.rst b/sp-docs/index.rst index 94ca71f5..8b196def 100644 --- a/sp-docs/index.rst +++ b/sp-docs/index.rst @@ -1,31 +1,21 @@ Documentation starter pack ========================== -*A pre-configured repository to build and publish documentation with Sphinx.* +The documentation starter pack helps you to quickly set up, build, and publish documentation with Sphinx. -The documentation starter pack includes: +It contains common styling and configuration through the `Canonical Sphinx`_ extension, supports both |RST| and Markdown, and includes automatic documentation checks. -* a bundled Sphinx_ theme, configuration, and extensions -* support for both reStructuredText (reST) and Markdown -* build checks for links, spelling, and inclusive language -* customisation support layered above a core configuration +The :ref:`quickstart` gives you a basic idea of how to start. +Detailed information is available for :ref:`setting up your documentation ` and for :ref:`updating it `. -This starter pack contains the files you need to quickly set up your Sphinx documentation. - -Before you start, see the information about `Read the Docs at Canonical`_ and the instructions for `How to publish documentation on Read the Docs`_. - -Then, to start setting up your docs, see :ref:`enable` for instructions. -The `Example product documentation`_ shows how to set up a Diátaxis structure in Sphinx. - -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. -(Open the files in your text editor; the rendered output is not very useful.) - -More information is available in the `reStructuredText style guide`_. +You can also find detailed information about the :ref:`automatic-checks` included in the starter pack, and a :ref:`list of projects ` that use the starter pack. .. toctree:: :hidden: :maxdepth: 2 - docs/quickstart - docs/enable - docs/work + /docs/quickstart + /docs/setup + /docs/update + /docs/automatic_checks + /docs/examples diff --git a/sp-docs/reuse/links.txt b/sp-docs/reuse/links.txt index 44a555ec..6ae01e69 100644 --- a/sp-docs/reuse/links.txt +++ b/sp-docs/reuse/links.txt @@ -1,8 +1,8 @@ .. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/ +.. _MyST style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/ .. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs .. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs .. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/ - .. wokeignore:rule=master .. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html .. wokeignore:rule=master @@ -12,27 +12,25 @@ .. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/ .. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/ .. _`Sphinx`: https://www.sphinx-doc.org/ - -.. |http://127.0.0.1:8000| replace:: ``http://127.0.0.1:8000`` -.. _`http://127.0.0.1:8000`: http://127.0.0.1:8000 -.. |sphinx-design| replace:: ``sphinx-design`` -.. _sphinx-design: https://sphinx-design.readthedocs.io/en/latest/ -.. |sphinx_tabs.tabs| replace:: ``sphinx_tabs.tabs`` -.. _sphinx_tabs.tabs: https://sphinx-tabs.readthedocs.io/en/latest/ -.. |sphinx_reredirects| replace:: ``sphinx_reredirects`` -.. _sphinx_reredirects: https://documatt.gitlab.io/sphinx-reredirects/ -.. |lxd-sphinx-extensions| replace:: ``lxd-sphinx-extensions`` -.. _lxd-sphinx-extensions: https://github.com/canonical/lxd-sphinx-extensions#lxd-sphinx-extensions -.. |sphinx_copybutton| replace:: ``sphinx_copybutton`` -.. _sphinx_copybutton: https://sphinx-copybutton.readthedocs.io/en/latest/ -.. |sphinxext.opengraph| replace:: ``sphinxext.opengraph`` -.. _sphinxext.opengraph: https://sphinxext-opengraph.readthedocs.io/en/latest/ -.. |myst_parser| replace:: ``myst_parser`` -.. _myst_parser: https://myst-parser.readthedocs.io/en/latest/ -.. |sphinxcontrib.jquery| replace:: ``sphinxcontrib.jquery`` -.. _sphinxcontrib.jquery: https://github.com/sphinx-contrib/jquery/ -.. |notfound.extension| replace:: ``notfound.extension`` -.. _notfound.extension: https://sphinx-notfound-page.readthedocs.io/en/latest/ - .. _woke documentation: https://docs.getwoke.tech/ignore -.. _#197: https://github.com/canonical/sphinx-docs-starter-pack/issues/197 +.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx +.. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log +.. _Open Graph: https://ogp.me/ +.. _manual import: https://readthedocs.com/dashboard/import/manual/ +.. _How to manually configure a Git repository integration: https://docs.readthedocs.io/en/stable/guides/setup/git-repo-manual.html +.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html +.. _Markdown: https://commonmark.org/ +.. _MyST: https://myst-parser.readthedocs.io/ +.. _Diátaxis: https://diataxis.fr/ +.. _Pa11y: https://pa11y.org/ +.. _Pa11y readme: https://github.com/pa11y/pa11y#command-line-configuration +.. _woke: https://github.com/get-woke/woke +.. _woke User Guide: https://docs.getwoke.tech/usage/#file-globs +.. _More useful markup: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/#more-useful-markup +.. _Vale: https://vale.sh/ +.. _Vale rules: https://github.com/canonical/praecepta +.. _Web Content Accessibility Guidelines (WCAG) 2.2: https://www.w3.org/TR/WCAG22/ +.. _Level AA conformance: https://www.w3.org/WAI/WCAG2AA-Conformance + +.. SHORTCUTS +.. |RST| replace:: :abbr:`reST (reStructuredText)` From 75412db9be3664171dc3f8365d0c7a7be95137b2 Mon Sep 17 00:00:00 2001 From: Ruth Fuchss Date: Mon, 8 Jul 2024 19:20:33 +0200 Subject: [PATCH 2/4] cannot do parallel builds for now We need https://github.com/canonical/canonical-sphinx/issues/27 to be fixed before we can enable parallel builds. Signed-off-by: Ruth Fuchss --- sp-files/Makefile.sp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sp-files/Makefile.sp b/sp-files/Makefile.sp index af60e282..a7f4a712 100644 --- a/sp-files/Makefile.sp +++ b/sp-files/Makefile.sp @@ -7,7 +7,7 @@ # You can set these variables from the command line, and also # from the environment for the first two. SPHINXDIR = .sphinx -SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees -j auto +SPHINXOPTS ?= -c . -d $(SPHINXDIR)/.doctrees SPHINXBUILD ?= $(VENVDIR)/bin/sphinx-build SOURCEDIR = . BUILDDIR = _build From 6b1f4473619cc818eae34edcbb2c02457f91dc30 Mon Sep 17 00:00:00 2001 From: Ruth Fuchss Date: Tue, 9 Jul 2024 09:01:20 +0200 Subject: [PATCH 3/4] add some common terms to the wordlist Signed-off-by: Ruth Fuchss --- sp-files/.sphinx/.wordlist.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/sp-files/.sphinx/.wordlist.txt b/sp-files/.sphinx/.wordlist.txt index 957dfc0e..fb4137d3 100644 --- a/sp-files/.sphinx/.wordlist.txt +++ b/sp-files/.sphinx/.wordlist.txt @@ -26,9 +26,14 @@ Kubernetes Launchpad linter LTS +LXD Makefile +Makefiles Matrix Mattermost +MicroCeph +MicroCloud +MicroOVN MyST namespace namespaces @@ -52,4 +57,5 @@ Ubuntu UI UUID VM +webhook YAML From 7b8207d8b740981c61cb0ef06674abbf55e7e85e Mon Sep 17 00:00:00 2001 From: Ruth Fuchss Date: Mon, 22 Jul 2024 13:21:46 +0200 Subject: [PATCH 4/4] add a README with a link to the documentation Signed-off-by: Ruth Fuchss --- README.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 README.rst diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..eba99a39 --- /dev/null +++ b/README.rst @@ -0,0 +1 @@ +See the documentation at https://canonical-starter-pack.readthedocs-hosted.com/use-canonical-sphinx-extension/