From 1a6274ed78bb30eb7b4249f9ef16b49106f9c5ce Mon Sep 17 00:00:00 2001 From: Kian Parvin Date: Tue, 7 May 2024 09:42:22 +0200 Subject: [PATCH 1/4] Fixed links --- contribute.rst | 2 +- how-to/add_controller.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/contribute.rst b/contribute.rst index f03c526..35dec67 100644 --- a/contribute.rst +++ b/contribute.rst @@ -30,5 +30,5 @@ footer of every page. For this documentation we use Sphinx and reStructuredText (reST), which is the default plain text markup language used by Sphinx. Here are some useful resources on reStructuredText: -- `Sphinx reStructuredText Primer `_ +- `Sphinx reStructuredText Primer `_ - `reStructuredText style guide `_ diff --git a/how-to/add_controller.rst b/how-to/add_controller.rst index 2ba625f..fe1c37e 100644 --- a/how-to/add_controller.rst +++ b/how-to/add_controller.rst @@ -94,7 +94,7 @@ Deploy controller ``juju status --format json | jq '.applications.haproxy.units["haproxy/0"]["public-address"]'`` -10. Go to the `Route 53 dashboard `_. +10. Go to the `Route 53 dashboard `__. 11. Add an A record for the deployed controller and the DNS name specified in step 1 with the IP obtained in step 9. @@ -102,7 +102,7 @@ Deploy controller ``juju run-action --wait certbot/0 get-certificate agree-tos=true aws-access-key-id= aws-secret-access-key= domains= email= plugin=dns-route53`` -13. Install the JAAS snap that you download from `here `_. +13. Install the JAAS snap that you download from `here `__. 14. To add the bootstrapped controller to JIMM we need to create a controller-information document. To do this, run the following command: From a210fd1fe62d3281b43a7e5f0e84731a2ace1616 Mon Sep 17 00:00:00 2001 From: Kian Parvin Date: Tue, 7 May 2024 09:49:41 +0200 Subject: [PATCH 2/4] Add ignore for woke --- contribute.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/contribute.rst b/contribute.rst index 35dec67..98a6e83 100644 --- a/contribute.rst +++ b/contribute.rst @@ -30,5 +30,6 @@ footer of every page. For this documentation we use Sphinx and reStructuredText (reST), which is the default plain text markup language used by Sphinx. Here are some useful resources on reStructuredText: +.. wokeignore:rule=master - `Sphinx reStructuredText Primer `_ - `reStructuredText style guide `_ From f6f6a599a09a78fcd5a9f7703d972ca69398eb43 Mon Sep 17 00:00:00 2001 From: Kian Parvin <46668016+kian99@users.noreply.github.com> Date: Tue, 7 May 2024 12:19:43 +0200 Subject: [PATCH 3/4] Fix woke errors and overall improvements (#39) * Fix woke errors and overall improvements * Be more consistent in use of code blocks * Fix woke Woke doesn't like non ascii characters --- .github/workflows/automatic-doc-checks.yml | 10 +- Makefile | 3 + contribute.rst | 4 +- custom_conf.py | 1 + how-to/deploy_candid_k8s.rst | 7 +- how-to/deploy_jimm_k8s.rst | 6 +- starter-guide.rst | 457 +++++++++++++++++++++ tutorial/jaas_basics.rst | 7 +- 8 files changed, 479 insertions(+), 16 deletions(-) create mode 100644 starter-guide.rst diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml index a6eb0ab..ed42e98 100644 --- a/.github/workflows/automatic-doc-checks.yml +++ b/.github/workflows/automatic-doc-checks.yml @@ -13,4 +13,12 @@ jobs: documentation-checks: uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main with: - working-directory: '.' \ No newline at end of file + working-directory: '.' + build: + name: Build + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Build with warnings as errors + run: make check-html-build diff --git a/Makefile b/Makefile index 30ae665..1f73533 100644 --- a/Makefile +++ b/Makefile @@ -74,6 +74,9 @@ run: install html: install . $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) +check-html-build: install + . $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -E --fail-on-warning --keep-going $(SPHINXOPTS) + epub: install . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) diff --git a/contribute.rst b/contribute.rst index 98a6e83..67fd78d 100644 --- a/contribute.rst +++ b/contribute.rst @@ -29,7 +29,5 @@ footer of every page. For this documentation we use Sphinx and reStructuredText (reST), which is the default plain text markup language used by Sphinx. Here are some useful resources on reStructuredText: - -.. wokeignore:rule=master -- `Sphinx reStructuredText Primer `_ +- `Sphinx reStructuredText Primer `_ :none:`wokeignore:rule=master,` - `reStructuredText style guide `_ diff --git a/custom_conf.py b/custom_conf.py index 6bf4031..f141bef 100644 --- a/custom_conf.py +++ b/custom_conf.py @@ -171,6 +171,7 @@ custom_excludes = [ 'doc-cheat-sheet*', 'README.md', + 'starter-guide.rst', ] # Add CSS files (located in .sphinx/_static/) diff --git a/how-to/deploy_candid_k8s.rst b/how-to/deploy_candid_k8s.rst index 90e152d..ca00127 100644 --- a/how-to/deploy_candid_k8s.rst +++ b/how-to/deploy_candid_k8s.rst @@ -137,11 +137,10 @@ Appendix Don’t have a PostgreSQL database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. wokeignore:rule=master -In case you do not have access to a PostgreSQL database you can use Amazon’s RDS to create one. Navigate to the RDS console and select “Create database”. Under “Engine type” select “PostgreSQL”, specify “Master username” and “Master password”. Also make sure to select “Public access” as “Yes”. You can customise all other options to your preference. Once the database is created, navigate to the database’s dashboard. There you will see the “Endpoint” and “Port” strings, which you will need to connect to the database. Use the following command to configure Candid: +In case you do not have access to a PostgreSQL database you can use Amazon's RDS to create one. Navigate to the RDS console and select "Create database". Under "Engine type" select "PostgreSQL", specify "Master username" and "Master password". Also make sure to select "Public access" as "Yes". You can customise all other options to your preference. Once the database is created, navigate to the database's dashboard. There you will see the "Endpoint" and "Port" strings, which you will need to connect to the database. :none:`wokeignore:rule=master,` +Use the following command to configure Candid: :none:`wokeignore:rule=master,` -.. wokeignore:rule=master -``juju config candid-k8s dns=’postgres://:@:/`` + ``juju config candid-k8s dns=postgres://:@:/`` :none:`wokeignore:rule=master,` Don’t have certificates ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/how-to/deploy_jimm_k8s.rst b/how-to/deploy_jimm_k8s.rst index 4580775..d0140b8 100644 --- a/how-to/deploy_jimm_k8s.rst +++ b/how-to/deploy_jimm_k8s.rst @@ -107,11 +107,9 @@ Appendix Don’t have a PostgreSQL database ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. wokeignore:rule=master -In case you do not have access to a PostgreSQL database you can use Amazon’s RDS to create one. Navigate to the RDS console and select “Create database”. Under “Engine type” select “PostgreSQL”, specify “Master username” and “Master password”. Also make sure to select “Public access” as “Yes”. You can customise all other options to your preference. Once the database is created, navigate to the database’s dashboard. There you will see the “Endpoint” and “Port” strings, which you will need to connect to the database. Use the following command to configure JIMM: +In case you do not have access to a PostgreSQL database you can use Amazon's RDS to create one. Navigate to the RDS console and select "Create database". Under "Engine type" select "PostgreSQL", specify "Master username" and "Master password". Also make sure to select "Public access" as "Yes". You can customise all other options to your preference. Once the database is created, navigate to the database's dashboard. There you will see the "Endpoint" and "Port" strings, which you will need to connect to the database. Use the following command to configure JIMM: :none:`wokeignore:rule=master,` -.. wokeignore:rule=master -``juju config jimm-k8s dns=’postgres://:@:/`` + ``juju config jimm-k8s dns=postgres://:@:/`` :none:`wokeignore:rule=master,` Don’t have certificates ~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/starter-guide.rst b/starter-guide.rst new file mode 100644 index 0000000..700a1b0 --- /dev/null +++ b/starter-guide.rst @@ -0,0 +1,457 @@ +:hide-toc: + +Documentation starter pack +========================== + +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`_ + + * `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. + +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. The next two sections show the steps needed for each scenario. + +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 +then commit all files to the documentation repository. + +You don't need to move any files, and you don't need to do any special +configuration on Read the Docs. + +Here is one way to do this for newly-created fictional docs repository +``canonical/alpha-docs``: + +.. code-block:: none + + git clone git@github.com:canonical/sphinx-docs-starter-pack alpha-docs + cd alpha-docs + rm -rf .git + git init + git branch -m main + UPDATE THE CONFIGURATION AND BUILD THE DOCS + git add -A + git commit -m "Import sphinx-docs-starter-pack" + git remote add upstream git@github.com:canonical/alpha-docs + git push -f upstream main + +Documentation in a code repository +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To add documentation to an existing code repository: + +#. create a directory called ``docs`` at the root of the code repository +#. populate the above directory with the contents of the starter pack + repository (with the exception of the ``.git`` directory) +#. copy the file(s) located in the ``docs/.github/workflows`` directory into + the code repository's ``.github/workflows`` directory +#. in the above workflow file(s), change the value of the ``working-directory`` field from ``.`` to ``docs`` +#. create a symbolic link to the ``docs/.wokeignore`` file from the root directory of the code repository +#. in file ``docs/.readthedocs.yaml`` set the following: + + * ``post_checkout: cd docs && python3 build_requirements.py`` + * ``configuration: docs/conf.py`` + * ``requirements: docs/.sphinx/requirements.txt`` + +**Note:** When configuring RTD itself for your project, the setting "Path for +``.readthedocs.yaml``" (under **Advanced Settings**) will need to be given the +value of ``docs/.readthedocs.yaml``. + +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_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|_ + +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: + +* install prerequisite software +* view the documentation + +Install prerequisite software +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To install the 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. + +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 do several things: + +* activate the virtual environment +* build the documentation +* serve the documentation on **127.0.0.1:8000** +* rebuild the documentation each time a file is saved +* send a reload page signal to the browser when the documentation is rebuilt + +The ``run`` target is therefore very convenient when preparing to submit a +change to the documentation. + +.. 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 +~~~~~~~~~~~~ + +Before committing and pushing changes, it's a good practice to run various checks locally to catch issues early in the development process. + +Local build +^^^^^^^^^^^ + +Run a clean build of the docs to surface any build errors that would occur in RTD: + +.. code-block:: none + + make clean-doc + make html + +Spelling check +^^^^^^^^^^^^^^ + +Ensure there are no spelling errors in the documentation: + +.. code-block:: shell + + make spelling + +Inclusive language check +^^^^^^^^^^^^^^^^^^^^^^^^ + +Ensure the documentation uses inclusive language: + +.. code-block:: shell + + make woke + +Link check +^^^^^^^^^^ + +Validate links within the documentation: + +.. code-block:: shell + + make linkcheck + +Configure the 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 ``.wordlist.txt``, because this file is maintained and updated centrally and contains words that apply across all projects. + +Customisation of inclusive language checks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 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 `_ + +.. LINKS + +.. wokeignore:rule=master +.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html +.. wokeignore:rule=master +.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html +.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/ + +.. |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/ + +.. _woke documentation: https://docs.getwoke.tech/ignore \ No newline at end of file diff --git a/tutorial/jaas_basics.rst b/tutorial/jaas_basics.rst index b9d7316..d999342 100644 --- a/tutorial/jaas_basics.rst +++ b/tutorial/jaas_basics.rst @@ -51,7 +51,7 @@ The first component we need to deploy is Candid, so let’s begin by creating a ``juju add-model candid`` -To deploy Candid please download `this `_ tarball, +To deploy Candid please download `this `__ tarball, which contains everything you will need. Extract the tarball: @@ -136,7 +136,7 @@ Let’s add a new Juju model for JIMM: ``juju add-model jimm`` -To deploy JIMM please download `this `_ tarball and extract it: +To deploy JIMM please download `this `__ tarball and extract it: ``tar xvf jimm.tar.xz`` @@ -362,8 +362,7 @@ you will want to install the ``kubectl`` snap: and fetch the config file from the newly deployed cluster: -.. wokeignore:rule=master -``juju scp kubernetes-master/0:config ~/.kube/config`` + ``juju scp kubernetes-master/0:config ~/.kube/config`` :none:`wokeignore:rule=master,` You can verify everything is configured correctly and see the cluster by running: From 92fe4b6f3f14f3209d64dab59983c9135ccf7908 Mon Sep 17 00:00:00 2001 From: Kian Parvin Date: Tue, 7 May 2024 16:30:31 +0200 Subject: [PATCH 4/4] Remove extras added --- .github/workflows/automatic-doc-checks.yml | 8 -------- Makefile | 5 +---- 2 files changed, 1 insertion(+), 12 deletions(-) diff --git a/.github/workflows/automatic-doc-checks.yml b/.github/workflows/automatic-doc-checks.yml index ed42e98..ef15c43 100644 --- a/.github/workflows/automatic-doc-checks.yml +++ b/.github/workflows/automatic-doc-checks.yml @@ -14,11 +14,3 @@ jobs: uses: canonical/documentation-workflows/.github/workflows/documentation-checks.yaml@main with: working-directory: '.' - build: - name: Build - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Build with warnings as errors - run: make check-html-build diff --git a/Makefile b/Makefile index 1f73533..ea4b93f 100644 --- a/Makefile +++ b/Makefile @@ -72,10 +72,7 @@ run: install # Doesn't depend on $(BUILDDIR) to rebuild properly at every run. html: install - . $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) - -check-html-build: install - . $(VENV); $(SPHINXBUILD) -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -E --fail-on-warning --keep-going $(SPHINXOPTS) + . $(VENV); $(SPHINXBUILD) -W --keep-going -b dirhtml "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS) epub: install . $(VENV); $(SPHINXBUILD) -b epub "$(SOURCEDIR)" "$(BUILDDIR)" -w $(SPHINXDIR)/warnings.txt $(SPHINXOPTS)