From 15a143606b80a2679bca440cbf46abc9f0dce425 Mon Sep 17 00:00:00 2001 From: Vladimir <48120135+izmalk@users.noreply.github.com> Date: Tue, 7 Jan 2025 00:40:56 +0000 Subject: [PATCH 1/8] Update quickstart guide --- docs/content/quickstart.rst | 63 ++++++++++++++++++++++--------------- 1 file changed, 38 insertions(+), 25 deletions(-) diff --git a/docs/content/quickstart.rst b/docs/content/quickstart.rst index 045cb429..afee520a 100644 --- a/docs/content/quickstart.rst +++ b/docs/content/quickstart.rst @@ -1,46 +1,59 @@ .. _quickstart: Quickstart guide ----------------- +----------------- -The following steps will guide you through setting up your documentation using the starter pack and building an initial set of documentation. +This guide is about the starter pack setup and usage. -For more detailed information, see the other sections of the starter pack documentation. +Initial setup +************* -1. Download the :file:`init.sh` file from the starter pack repository and place it into the directory where you want to set up your documentation. +The following steps will guide you through setting 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. +#. Clone the [Starter pack](https://github.com/canonical/sphinx-docs-starter-pack) repository to a local folder. +#. Copy the following files to the same folders in the repo you want your documentation to be: + - `.github/workflows/*-checks.yml` -- documentation tests + - `docs` -- documentation content and sphinx files + - `.readthedocs.yaml` -- Readthedocs configuration file + - `.wokeignore` -- exceptions list for the non-inclusive language check +#. Configure your new documentation set by adjusting the copied `docs/conf.py` config file. Make sure to pay attention to all `TODO` comments. - See :ref:`enable` for detailed information on what the script does. +Build +***** -#. Enter the documentation folder (the folder you specified when running the script, such as :file:`docs/`) and build the documentation with the following command:: +To build the documentation, use the following command: - make run + .. code-block:: none - This command creates a virtual environment, installs the Python dependencies, builds the documentation, and serves it on :literalref:`http://127.0.0.1:8000/`. + make run - See :ref:`build` for detailed information on different commands for building and viewing the documentation. +This command creates a virtual environment, installs the Python dependencies, builds the documentation, and serves it on the :literalref:`http://127.0.0.1:8000/` address. -#. 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. +See the :ref:`build` page for more information on different commands for building and viewing the documentation. -#. 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: +Work on content +*************** - .. code-block:: rest +Keep the session with the `make run` command running to rebuild the documentation automatically whenever a file in the `docs/content` is saved, and open the :literalref:`http://127.0.0.1:8000/` address in a web browser to see the locally built and hosted documentation as HTML. - Reference - ========= +To add a new page to the documentation: - .. 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: + #. Create a new file. For example, to create the `Reference` page, create a document called :file:`reference.rst`, insert the following |RST|-formatted heading ``Reference`` at the beginning, and then save the file: + + .. code-block:: rest + :caption: reStructuredText example - .. code-block:: Markdown + The output of this line starts with four spaces. - # Reference + If you prefer to use Markdown syntax instead of |RST|, you can create a Markdown file instead. For example, :file:`reference.md` file with the following Markdown-formatted heading: -#. Open :file:`index.rst`. + .. code-block:: markdown + :caption: Markdown example + + # Reference + + #. Open the :file:`index.rst`. 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. - 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. The ``toctree`` section will now look like this: @@ -58,8 +71,8 @@ For more detailed information, see the other sections of the starter pack docume 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 ``. -#. Check :literalref:`http://127.0.0.1:8000/`. +#. Check the rendered documentation at the :literalref:`http://127.0.0.1:8000/` address in a web browser. - 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 the **Reference** page added to the navigation. -See :ref:`guidance` for links to more detailed information about |RST| and Markdown/MyST. +See :ref:`guidance` for links to more detailed information about the |RST| and Markdown/MyST syntax. From f54c69f28c406380c818a3301c08eec458ae696e Mon Sep 17 00:00:00 2001 From: Vladimir <48120135+izmalk@users.noreply.github.com> Date: Tue, 7 Jan 2025 21:59:23 +0000 Subject: [PATCH 2/8] Add edit page and finish updating de-init.sh --- docs/content/customise.rst | 82 +++++++++++++++++++++---------------- docs/content/edit.rst | 50 ++++++++++++++++++++++ docs/content/enable.rst | 68 +++++------------------------- docs/content/quickstart.rst | 80 ++++++++++++++---------------------- docs/content/update.rst | 1 + 5 files changed, 138 insertions(+), 143 deletions(-) create mode 100644 docs/content/edit.rst diff --git a/docs/content/customise.rst b/docs/content/customise.rst index a945af84..dc007a8e 100644 --- a/docs/content/customise.rst +++ b/docs/content/customise.rst @@ -3,41 +3,44 @@ 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. +Most configuration parameters can be set in the :file:`docs/conf.py` file. -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. +The starter pack's default configuration is prepared in a way that makes sense for most projects. +However, you must set some critical parameters that may be unique for your project, like the project's name. + +In addition, you can find some optional parameters or add your own configuration parameters to the file. Required customisation ---------------------- -You must check and update some of the configuration to adapt the documentation to your project. +You must check and update some of the parameters to the needs of your project. +Most of such mandatory parameters are commented with the `TODO` keyword. + +The following are some highlights of the available configuration parameters. Update the project information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Edit the :file:`conf.py` file and update the configuration in the ``Project information`` section. +Edit the :file:`docs/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`_. +This preview is configured through the Open Graph Protocol (OGP) configuration. 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 -~~~~~~~~~~~~~~~~~~~~ +Adjust 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". +The header is the top section of a page template. +By default, the starter pack template header contains your product tag image, product name (taken from the ``project`` setting in the :file:`docs/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. +In many cases, this default setup is sufficient, but you can customise 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. @@ -50,11 +53,12 @@ The starter pack contains several features that you can configure, or turn off i Deactivate the feedback button ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -By default, the starter pack includes a feedback button at the top of each page in the documentation. +By default, the starter pack includes a feedback button at the top of each page. 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``. +If your project does not use GitHub issues, set the ``github_issues`` variable in the :file:`docs/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:`docs/conf.py` file to ``True``. Configure the contributor display ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -62,7 +66,7 @@ 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``. +If you want to turn this contributor listing off, you can do so by setting the ``display_contributors`` variable in the :file:`docs/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"). @@ -73,38 +77,45 @@ 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. +You can add redirects in the ``redirects`` variable in the :file:`docs/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. +They are pre-configured as needed, but you can customise their configuration in the :file:`docs/conf.py` file. -The following extensions are always included: +The following extensions are included by default: -- :literalref:`myst_parser ` -- :literalref:`sphinxcontrib.jquery ` +* `canonical_sphinx` +* `sphinxcontrib.cairosvgconverter` +* `sphinx_last_updated_by_git` -The following extensions are included with the ``[full]`` optional install of canonical-sphinx: +The `canonical_sphinx` extension is required for the starter pack. +It automatically enables the following extensions: -- :literalref:`sphinx-design ` -- :literalref:`sphinx_copybutton ` -- :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:`notfound.extension ` +* `custom-rst-roles` +* `myst_parser` +* `notfound.extension` +* `related-links` +* `sphinx_copybutton` +* `sphinx_design` +* `sphinx_reredirects` +* `sphinx_tabs.tabs` +* `sphinxcontrib.jquery` +* `sphinxext.opengraph` +* `terminal-output` +* `youtube-links` -None of the extensions referenced in this section need to be added to the ``extensions`` variable in :file:`conf.py`. -If the extensions need specific Python packages, add those to the :file:`requirements.txt` file. +To add new extensions needed for your documentation set, use the `extensions` parameter. +If the extensions need specific Python packages, add those to the :file:`.sphinx/requirements.txt` 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. +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:`docs/conf.py` file. .. code:: python @@ -133,7 +144,7 @@ MyST:: [Page contents] Possible values for the ``sequential_nav`` field are ``none``, ``prev``, ``next``, and ``both``. -See the :file:`conf.py` file for more information. +See the :file:`docs/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`_. @@ -141,8 +152,7 @@ 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. +A custom configuration parameter for your project 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: diff --git a/docs/content/edit.rst b/docs/content/edit.rst new file mode 100644 index 00000000..e77959a8 --- /dev/null +++ b/docs/content/edit.rst @@ -0,0 +1,50 @@ +.. _edit: + +Edit content +============ + +The landing page is stored in the :file:`docs/index.rst` file +while the rest of the pages are stored in the :file:`docs/content/` folder. + +The navigation menu structure is set by the `.. toctree::` blocks used to list all nested pages for a page. +The :file:`index.rst` page's toctree contains the top level navigation menu. + +To add a new page to the documentation: + +1. Create a new file in the `docs/content` folder. For example, to create the `Reference` page, create a document called :file:`reference.rst`, insert the following |RST|-formatted heading ``Reference`` at the beginning, and then save the file: + + .. code-block:: rest + :caption: reStructuredText title example + + Reference + ========= + + If you prefer to use Markdown (MyST) syntax instead of |RST|, you can create a Markdown file. For example, :file:`reference.md` file with the following Markdown-formatted heading at the beginning: + + .. code-block:: markdown + :caption: Markdown title example + + # Reference + +2. Add the new file to the navigation menu. Open the :file:`index.rst` file or another page that you want to add a nested page to. At the bottom of the file locate the ``toctree`` block and add a properly indented line containing the path (without a file extension) to the new file created in the first step. For example, ``content/reference``. + + The ``toctree`` block will now look like this: + + .. code-block:: rest + :caption: Toctree block example + + .. toctree:: + :hidden: + :maxdepth: 2 + /content/quickstart + /content/setup + /content/update + /content/automatic_checks + /content/examples + /content/contributing + /content/reference + + +The documentation will now show the new page added to the navigation. + +By default, the page's title (the first heading in the file) is used for the navigation menu entry. You can overwrite a name of a Nav Menu element by specifying it explicitly in the toctree block, for example: `Reference `. diff --git a/docs/content/enable.rst b/docs/content/enable.rst index 29cdae7c..707ca8da 100644 --- a/docs/content/enable.rst +++ b/docs/content/enable.rst @@ -1,63 +1,17 @@ .. _enable: -Enable the starter pack -======================= +Copy the starter pack +===================== -You can use the starter pack to set up your documentation in one of the following ways: +Make sure to copy all required starter pack files to initialise a new documentation set: -- As a standalone documentation project in a new repository -- In a dedicated documentation folder in an existing code repository +#. Clone the `Starter pack `_ repository to a temporary local folder +#. Copy the following folders and files from the starer pack temporary folder to the same paths in the repo you want your documentation to be: -The starter pack provides a shell script that updates and copies the starter pack files to the selected location. + - :file:`.github/workflows/*-checks.yml` -- documentation tests + - :file:`docs` -- your documentation folder. Original content includes initial documentation pages (you are reading one of them) and internal Sphinx files + - :file:`.readthedocs.yaml` -- the Readthedocs configuration file + - :file:`.wokeignore` -- a list of exceptions for the non-inclusive language check -.. 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. - - 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`. - - -Run the initialisation script ------------------------------ - -The initialisation script will download all required files, update them, and copy them to the selected location. - -1. Download :file:`init.sh` from the starter pack repository. -#. Put the script into the root folder of the Git repository in which you want to enable the starter pack. - - This can be a new, empty repository or your code repository. -#. Make the script executable:: - - chmod u+x init.sh -#. Run the script:: - - ./init.sh -#. When prompted, enter the installation directory: - - - For standalone repositories, enter a full stop (``.``). - - For documentation in code repositories, enter the name of the documentation folder (for example, ``docs``). - - 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. -#. When prompted, specify if you'll be using ``.rst`` or ``.md`` -#. Check the output for any warnings or errors. - -You can now delete the :file:`init.sh` file. - -.. _enable-behind-the-scenes: - -Behind the scenes ------------------ - -We recommend using the initialisation script to enable the starter pack. -Here's a summary of what it does: - -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. +After copying starter pack files to your repository continue by configuring your documentation set via the :file:`docs/conf.py` config file. +For more information on configuration pararmeters, see the :ref:`customise` page. diff --git a/docs/content/quickstart.rst b/docs/content/quickstart.rst index afee520a..7c686dbe 100644 --- a/docs/content/quickstart.rst +++ b/docs/content/quickstart.rst @@ -10,69 +10,49 @@ Initial setup The following steps will guide you through setting up your documentation: -#. Clone the [Starter pack](https://github.com/canonical/sphinx-docs-starter-pack) repository to a local folder. -#. Copy the following files to the same folders in the repo you want your documentation to be: - - `.github/workflows/*-checks.yml` -- documentation tests - - `docs` -- documentation content and sphinx files - - `.readthedocs.yaml` -- Readthedocs configuration file - - `.wokeignore` -- exceptions list for the non-inclusive language check -#. Configure your new documentation set by adjusting the copied `docs/conf.py` config file. Make sure to pay attention to all `TODO` comments. +#. Clone the `Starter pack `_ repository to a temporary local folder. +#. Copy the following folders and files from the starer pack to the same paths in the repo you want your documentation to be: -Build -***** - -To build the documentation, use the following command: - - .. code-block:: none - - make run - -This command creates a virtual environment, installs the Python dependencies, builds the documentation, and serves it on the :literalref:`http://127.0.0.1:8000/` address. + - :file:`.github/workflows/*-checks.yml` + - :file:`docs` + - :file:`.readthedocs.yaml` + - :file:`.wokeignore` +#. Configure your new documentation set by adjusting the copied :file:`docs/conf.py` config file. -See the :ref:`build` page for more information on different commands for building and viewing the documentation. +For more information on the initial setup, see the :ref:`setup` section. -Work on content -*************** - -Keep the session with the `make run` command running to rebuild the documentation automatically whenever a file in the `docs/content` is saved, and open the :literalref:`http://127.0.0.1:8000/` address in a web browser to see the locally built and hosted documentation as HTML. - -To add a new page to the documentation: - - #. Create a new file. For example, to create the `Reference` page, create a document called :file:`reference.rst`, insert the following |RST|-formatted heading ``Reference`` at the beginning, and then save the file: +Build +***** - .. code-block:: rest - :caption: reStructuredText example +Starter pack needs the following packages installed: - The output of this line starts with four spaces. +* `make` +* `python3` +* `python3-venv` +* `python3-pip` - If you prefer to use Markdown syntax instead of |RST|, you can create a Markdown file instead. For example, :file:`reference.md` file with the following Markdown-formatted heading: +To build documentation, use the following command: - .. code-block:: markdown - :caption: Markdown example - - # Reference - - #. Open the :file:`index.rst`. 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. +.. code-block:: - This is the navigation title for the new document and its filename without the extension. + make run - The ``toctree`` section will now look like this: +This command creates a virtual environment, installs the Python dependencies, builds the documentation, and serves it on the :literalref:`http://127.0.0.1:8000/` address. - .. code-block:: rest +For more information on different commands for building and viewing the documentation, see the :ref:`build` page. - .. toctree:: - :hidden: - :maxdepth: 2 +Update content +************** - self - Reference +The landing page is stored in the :file:`docs/index.rst` file +while the rest of the pages are stored in the :file:`docs/content` folder. - .. 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 ``. +For more information on how to edit existing files, see the :ref:`edit` page. -#. Check the rendered documentation at the :literalref:`http://127.0.0.1:8000/` address in a web browser. +To check the rendered documentation: - The documentation will now show the **Reference** page added to the navigation. +1. Build the documentation as instructed in the Build section above. +2. Keep the `make run` command running in the terminal to rebuild the documentation automatically whenever a file in the `docs/content` is saved. +3. Open the :literalref:`http://127.0.0.1:8000/` address in a web browser to see the locally built and hosted documentation as HTML. -See :ref:`guidance` for links to more detailed information about the |RST| and Markdown/MyST syntax. +For more information about the |RST| and Markdown/MyST syntax and other useful resources, see the :ref:`guidance` page. diff --git a/docs/content/update.rst b/docs/content/update.rst index 0afc771d..29036751 100644 --- a/docs/content/update.rst +++ b/docs/content/update.rst @@ -12,4 +12,5 @@ You'll find information on how to build and preview the documentation, and some /content/prereqs /content/build + /content/edit /content/guidance From b9f7dc64ce1d476de84ac6ef24d4c96ed735ade5 Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Wed, 8 Jan 2025 17:24:33 +0000 Subject: [PATCH 3/8] Simplified quickstart instructions (#1) * Simplified quickstart instructions * Apply suggestions from code review --------- Co-authored-by: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> --- docs/content/quickstart.rst | 57 +++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 31 deletions(-) diff --git a/docs/content/quickstart.rst b/docs/content/quickstart.rst index 7c686dbe..953b9d75 100644 --- a/docs/content/quickstart.rst +++ b/docs/content/quickstart.rst @@ -1,58 +1,53 @@ .. _quickstart: +================ Quickstart guide ------------------ +================ -This guide is about the starter pack setup and usage. +This page contains a short guide on how to set up and use the starter pack. For more information, see the respective sections of the starter pack documentation: +:ref:`setup`, :ref:`update`, :ref:`automatic-checks`. Initial setup -************* +============= -The following steps will guide you through setting up your documentation: +Clone the `Starter pack `_ repository to a temporary local folder. -#. Clone the `Starter pack `_ repository to a temporary local folder. -#. Copy the following folders and files from the starer pack to the same paths in the repo you want your documentation to be: +Copy the following folders and files preserving their paths from the starter pack to the repository you want your documentation to be: - - :file:`.github/workflows/*-checks.yml` - :file:`docs` - :file:`.readthedocs.yaml` - :file:`.wokeignore` -#. Configure your new documentation set by adjusting the copied :file:`docs/conf.py` config file. + - :file:`.github/workflows/*-checks.yml` -For more information on the initial setup, see the :ref:`setup` section. -Build -***** +Build and run the local server +============================== -Starter pack needs the following packages installed: +Prerequisites (which you probably have installed already) are: -* `make` -* `python3` -* `python3-venv` -* `python3-pip` +* ``make`` +* ``python3`` +* ``python3-venv`` +* ``python3-pip`` -To build documentation, use the following command: +In :file:`docs` run:: -.. code-block:: + make run - make run +This: creates and activates a virtual environment in :file:`docs/.sphinx/venv`, builds the documentation and serves it at :literalref:`http://127.0.0.1:8000/`. -This command creates a virtual environment, installs the Python dependencies, builds the documentation, and serves it on the :literalref:`http://127.0.0.1:8000/` address. +The server watches the source files, including :file:`conf.py`, and rebuilds automatically on changes. -For more information on different commands for building and viewing the documentation, see the :ref:`build` page. -Update content -************** +Adjust config +============= -The landing page is stored in the :file:`docs/index.rst` file -while the rest of the pages are stored in the :file:`docs/content` folder. +Work through the settings in :file:`conf.py`. Most parameters can be left as they are or simply ignored. They can all be changed later. -For more information on how to edit existing files, see the :ref:`edit` page. -To check the rendered documentation: +Update content +============== + +The landing page is :file:`docs/index.rst`. Other pages are under :file:`docs/content`. -1. Build the documentation as instructed in the Build section above. -2. Keep the `make run` command running in the terminal to rebuild the documentation automatically whenever a file in the `docs/content` is saved. -3. Open the :literalref:`http://127.0.0.1:8000/` address in a web browser to see the locally built and hosted documentation as HTML. -For more information about the |RST| and Markdown/MyST syntax and other useful resources, see the :ref:`guidance` page. From 55066d35171acc2134739830aaa7cbdb65d37f4c Mon Sep 17 00:00:00 2001 From: Vladimir <48120135+izmalk@users.noreply.github.com> Date: Wed, 8 Jan 2025 17:48:42 +0000 Subject: [PATCH 4/8] Spellcheck fixes --- docs/content/customise.rst | 32 ++++++++++++++++---------------- docs/content/edit.rst | 12 +++++------- docs/content/enable.rst | 10 +++++----- docs/content/quickstart.rst | 8 ++------ 4 files changed, 28 insertions(+), 34 deletions(-) diff --git a/docs/content/customise.rst b/docs/content/customise.rst index dc007a8e..a25d6ef7 100644 --- a/docs/content/customise.rst +++ b/docs/content/customise.rst @@ -28,7 +28,7 @@ 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 the Open Graph Protocol (OGP) configuration. +This preview is configured through the Open Graph Protocol (:spellexception:`OGP`) configuration. 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. @@ -87,25 +87,25 @@ They are pre-configured as needed, but you can customise their configuration in The following extensions are included by default: -* `canonical_sphinx` -* `sphinxcontrib.cairosvgconverter` -* `sphinx_last_updated_by_git` +* ``canonical_sphinx`` +* ``sphinxcontrib.cairosvgconverter`` +* ``sphinx_last_updated_by_git`` The `canonical_sphinx` extension is required for the starter pack. It automatically enables the following extensions: -* `custom-rst-roles` -* `myst_parser` -* `notfound.extension` -* `related-links` -* `sphinx_copybutton` -* `sphinx_design` -* `sphinx_reredirects` -* `sphinx_tabs.tabs` -* `sphinxcontrib.jquery` -* `sphinxext.opengraph` -* `terminal-output` -* `youtube-links` +* ``custom-rst-roles`` +* ``myst_parser`` +* ``notfound.extension`` +* ``related-links`` +* ``sphinx_copybutton`` +* ``sphinx_design`` +* ``sphinx_reredirects`` +* ``sphinx_tabs.tabs`` +* ``sphinxcontrib.jquery`` +* ``sphinxext.opengraph`` +* ``terminal-output`` +* ``youtube-links`` To add new extensions needed for your documentation set, use the `extensions` parameter. If the extensions need specific Python packages, add those to the :file:`.sphinx/requirements.txt` file. diff --git a/docs/content/edit.rst b/docs/content/edit.rst index e77959a8..8a723dd2 100644 --- a/docs/content/edit.rst +++ b/docs/content/edit.rst @@ -6,12 +6,12 @@ Edit content The landing page is stored in the :file:`docs/index.rst` file while the rest of the pages are stored in the :file:`docs/content/` folder. -The navigation menu structure is set by the `.. toctree::` blocks used to list all nested pages for a page. -The :file:`index.rst` page's toctree contains the top level navigation menu. +The Navigation Menu structure is set by the ``.. toctree::`` blocks used to list all nested pages for a page. +The :file:`index.rst` page's ``toctree`` block contains the top level Navigation Menu. To add a new page to the documentation: -1. Create a new file in the `docs/content` folder. For example, to create the `Reference` page, create a document called :file:`reference.rst`, insert the following |RST|-formatted heading ``Reference`` at the beginning, and then save the file: +1. Create a new file in the `docs/content` folder. For example, to create the **Reference** page, create a document called :file:`reference.rst`, insert the following |RST|-formatted heading ``Reference`` at the beginning, and then save the file: .. code-block:: rest :caption: reStructuredText title example @@ -26,12 +26,11 @@ To add a new page to the documentation: # Reference -2. Add the new file to the navigation menu. Open the :file:`index.rst` file or another page that you want to add a nested page to. At the bottom of the file locate the ``toctree`` block and add a properly indented line containing the path (without a file extension) to the new file created in the first step. For example, ``content/reference``. +2. Add the new file to the Navigation Menu. Open the :file:`index.rst` file or another page that you want to add a nested page to. At the bottom of the file locate the ``toctree`` block and add a properly indented line containing the path (without a file extension) to the new file created in the first step. For example, ``content/reference``. The ``toctree`` block will now look like this: .. code-block:: rest - :caption: Toctree block example .. toctree:: :hidden: @@ -44,7 +43,6 @@ To add a new page to the documentation: /content/contributing /content/reference - The documentation will now show the new page added to the navigation. -By default, the page's title (the first heading in the file) is used for the navigation menu entry. You can overwrite a name of a Nav Menu element by specifying it explicitly in the toctree block, for example: `Reference `. +By default, the page's title (the first heading in the file) is used for the Navigation Menu entry. You can overwrite a name of a Menu element by specifying it explicitly in the ``toctree`` block, for example: `Reference `. diff --git a/docs/content/enable.rst b/docs/content/enable.rst index 707ca8da..3e00bf92 100644 --- a/docs/content/enable.rst +++ b/docs/content/enable.rst @@ -6,12 +6,12 @@ Copy the starter pack Make sure to copy all required starter pack files to initialise a new documentation set: #. Clone the `Starter pack `_ repository to a temporary local folder -#. Copy the following folders and files from the starer pack temporary folder to the same paths in the repo you want your documentation to be: +#. Copy the following folders and files from the starer pack temporary folder to the same paths in the repository you want your documentation to be: - - :file:`.github/workflows/*-checks.yml` -- documentation tests - :file:`docs` -- your documentation folder. Original content includes initial documentation pages (you are reading one of them) and internal Sphinx files - - :file:`.readthedocs.yaml` -- the Readthedocs configuration file + - :file:`.readthedocs.yaml` -- the **Read the Docs** configuration file - :file:`.wokeignore` -- a list of exceptions for the non-inclusive language check + - :file:`.github/workflows/*-checks.yml` -- documentation tests -After copying starter pack files to your repository continue by configuring your documentation set via the :file:`docs/conf.py` config file. -For more information on configuration pararmeters, see the :ref:`customise` page. +After copying starter pack files to your repository continue by configuring your documentation set via the :file:`docs/conf.py` :spellexception:`config file`. +For more information on configuration parameters, see the :ref:`customise` page. diff --git a/docs/content/quickstart.rst b/docs/content/quickstart.rst index 953b9d75..d4b9faf4 100644 --- a/docs/content/quickstart.rst +++ b/docs/content/quickstart.rst @@ -38,16 +38,12 @@ This: creates and activates a virtual environment in :file:`docs/.sphinx/venv`, The server watches the source files, including :file:`conf.py`, and rebuilds automatically on changes. - -Adjust config -============= +Configure +========= Work through the settings in :file:`conf.py`. Most parameters can be left as they are or simply ignored. They can all be changed later. - Update content ============== The landing page is :file:`docs/index.rst`. Other pages are under :file:`docs/content`. - - From 9bdb4aaea523eba4421aa7cf8859bbc5fbd7a48e Mon Sep 17 00:00:00 2001 From: Vladimir Izmalkov <48120135+izmalk@users.noreply.github.com> Date: Tue, 14 Jan 2025 12:51:56 +0100 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Michael Park Co-authored-by: Artem Konev <141050460+akcano@users.noreply.github.com> --- docs/content/customise.rst | 24 +++++++++++++----------- docs/content/edit.rst | 29 +++++++++++++++-------------- docs/content/enable.rst | 6 +++--- docs/content/quickstart.rst | 10 +++++----- 4 files changed, 36 insertions(+), 33 deletions(-) diff --git a/docs/content/customise.rst b/docs/content/customise.rst index a25d6ef7..88aefa5b 100644 --- a/docs/content/customise.rst +++ b/docs/content/customise.rst @@ -3,18 +3,18 @@ Customise the setup =================== -Most configuration parameters can be set in the :file:`docs/conf.py` file. +Configuration for a starter pack based documentation is set in the :file:`docs/conf.py` [Sphinx configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html). The starter pack's default configuration is prepared in a way that makes sense for most projects. -However, you must set some critical parameters that may be unique for your project, like the project's name. +However, you must set some critical parameters that are unique for your project, like the project's name. In addition, you can find some optional parameters or add your own configuration parameters to the file. Required customisation ---------------------- -You must check and update some of the parameters to the needs of your project. -Most of such mandatory parameters are commented with the `TODO` keyword. +You must check and update some of the parameters specific to your project. +Mandatory parameters are commented with the `TODO` keyword. The following are some highlights of the available configuration parameters. @@ -38,9 +38,9 @@ Adjust the header ~~~~~~~~~~~~~~~~~ The header is the top section of a page template. -By default, the starter pack template header contains your product tag image, product name (taken from the ``project`` setting in the :file:`docs/conf.py` file), a link to your product page, and a drop-down menu for "More resources". +By default, the starter pack template header contains your product's tag image and name (taken from the ``project`` setting in the :file:`docs/conf.py` file), a link to your product's page (if available), and a drop-down menu for "More resources". -In many cases, this default setup is sufficient, but you can customise it. +The default configuration is sufficient for many cases but can be further customised. 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. @@ -58,7 +58,7 @@ This button redirects users to your GitHub issues page, and populates an issue f If your project does not use GitHub issues, set the ``github_issues`` variable in the :file:`docs/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:`docs/conf.py` file to ``True``. +If you want to deactivate the feedback button, but keep the link in the footer, set ``disable_feedback_button`` in the :file:`docs/conf.py` file to ``True``. Configure the contributor display ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -92,7 +92,7 @@ The following extensions are included by default: * ``sphinx_last_updated_by_git`` The `canonical_sphinx` extension is required for the starter pack. -It automatically enables the following extensions: +It automatically enables and sets default configurations for the following extensions: * ``custom-rst-roles`` * ``myst_parser`` @@ -107,8 +107,10 @@ It automatically enables the following extensions: * ``terminal-output`` * ``youtube-links`` -To add new extensions needed for your documentation set, use the `extensions` parameter. -If the extensions need specific Python packages, add those to the :file:`.sphinx/requirements.txt` file. +To add new extensions needed for your documentation set, add them to the ``extensions`` parameter in :file:`docs/conf.py`. +.. info:: + + If any additional extensions need specific Python packages, ensure they are installed alongside the other requirements by adding them to the :file:`.sphinx/requirements.txt` file. Add page-specific configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -152,7 +154,7 @@ See `Hiding Contents sidebar`_. Add your own configuration -------------------------- -A custom configuration parameter for your project 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. +Custom configuration parameters for your project 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: diff --git a/docs/content/edit.rst b/docs/content/edit.rst index 8a723dd2..2d1ad953 100644 --- a/docs/content/edit.rst +++ b/docs/content/edit.rst @@ -4,9 +4,9 @@ Edit content ============ The landing page is stored in the :file:`docs/index.rst` file -while the rest of the pages are stored in the :file:`docs/content/` folder. +while the rest of the pages are stored in the :file:`docs/content/` folder by default. -The Navigation Menu structure is set by the ``.. toctree::`` blocks used to list all nested pages for a page. +The Navigation Menu structure is set by ``.. toctree::`` [directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree). These directives define the hierarchy of included content throughout the documentation. The :file:`index.rst` page's ``toctree`` block contains the top level Navigation Menu. To add a new page to the documentation: @@ -26,23 +26,24 @@ To add a new page to the documentation: # Reference -2. Add the new file to the Navigation Menu. Open the :file:`index.rst` file or another page that you want to add a nested page to. At the bottom of the file locate the ``toctree`` block and add a properly indented line containing the path (without a file extension) to the new file created in the first step. For example, ``content/reference``. +2. Add the new page to the Navigation Menu: open the :file:`index.rst` file or another file where you want to nest the new page; at the bottom of the file, locate the ``toctree`` directive and add a properly indented line containing the path (without a file extension) to the new file created in the first step. For example, ``content/reference``. The ``toctree`` block will now look like this: .. code-block:: rest .. toctree:: - :hidden: - :maxdepth: 2 - /content/quickstart - /content/setup - /content/update - /content/automatic_checks - /content/examples - /content/contributing - /content/reference - -The documentation will now show the new page added to the navigation. + :hidden: + :maxdepth: 2 + + /content/quickstart + /content/setup + /content/update + /content/automatic_checks + /content/examples + /content/contributing + /content/reference + +The documentation will now show the new page added to the navigation when rebuilt. By default, the page's title (the first heading in the file) is used for the Navigation Menu entry. You can overwrite a name of a Menu element by specifying it explicitly in the ``toctree`` block, for example: `Reference `. diff --git a/docs/content/enable.rst b/docs/content/enable.rst index 3e00bf92..de8151e1 100644 --- a/docs/content/enable.rst +++ b/docs/content/enable.rst @@ -6,12 +6,12 @@ Copy the starter pack Make sure to copy all required starter pack files to initialise a new documentation set: #. Clone the `Starter pack `_ repository to a temporary local folder -#. Copy the following folders and files from the starer pack temporary folder to the same paths in the repository you want your documentation to be: +#. Copy the following folders and files from the starter pack temporary folder to the repository where you want your documentation, placing them at the same relative paths: - :file:`docs` -- your documentation folder. Original content includes initial documentation pages (you are reading one of them) and internal Sphinx files - :file:`.readthedocs.yaml` -- the **Read the Docs** configuration file - - :file:`.wokeignore` -- a list of exceptions for the non-inclusive language check + - :file:`.wokeignore` -- a list of exceptions for the inclusive language check - :file:`.github/workflows/*-checks.yml` -- documentation tests -After copying starter pack files to your repository continue by configuring your documentation set via the :file:`docs/conf.py` :spellexception:`config file`. +After copying the starter pack files to your repository, make sure to set the project's name and other configuration parameters in the :file:`docs/conf.py` :spellexception:`config file`. For more information on configuration parameters, see the :ref:`customise` page. diff --git a/docs/content/quickstart.rst b/docs/content/quickstart.rst index d4b9faf4..e4e46df1 100644 --- a/docs/content/quickstart.rst +++ b/docs/content/quickstart.rst @@ -23,25 +23,25 @@ Copy the following folders and files preserving their paths from the starter pac Build and run the local server ============================== -Prerequisites (which you probably have installed already) are: +To build HTML documentation the prerequisites are: * ``make`` * ``python3`` * ``python3-venv`` * ``python3-pip`` -In :file:`docs` run:: +In :file:`docs`, run:: make run -This: creates and activates a virtual environment in :file:`docs/.sphinx/venv`, builds the documentation and serves it at :literalref:`http://127.0.0.1:8000/`. +This creates and activates a virtual environment in :file:`docs/.sphinx/venv`, builds the documentation and serves it at :literalref:`http://127.0.0.1:8000/`. -The server watches the source files, including :file:`conf.py`, and rebuilds automatically on changes. +The server watches the source files, including :file:`docs/conf.py`, and rebuilds automatically on changes. Configure ========= -Work through the settings in :file:`conf.py`. Most parameters can be left as they are or simply ignored. They can all be changed later. +Work through the settings in :file:`docs/conf.py`. Most parameters can be left with the default values as they can be changed later. Update content ============== From d5c89474cec10584bc1cdae9d4b1b36fbed1602b Mon Sep 17 00:00:00 2001 From: Vladimir <48120135+izmalk@users.noreply.github.com> Date: Tue, 14 Jan 2025 12:01:11 +0000 Subject: [PATCH 6/8] Fix the inclusive language check Fix the inclusive language check by removing the link that has `master` in it --- docs/content/customise.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/customise.rst b/docs/content/customise.rst index 88aefa5b..bfdcf48c 100644 --- a/docs/content/customise.rst +++ b/docs/content/customise.rst @@ -3,7 +3,7 @@ Customise the setup =================== -Configuration for a starter pack based documentation is set in the :file:`docs/conf.py` [Sphinx configuration file](https://www.sphinx-doc.org/en/master/usage/configuration.html). +Configuration for a starter pack based documentation is set in the :file:`docs/conf.py` Sphinx configuration file. The starter pack's default configuration is prepared in a way that makes sense for most projects. However, you must set some critical parameters that are unique for your project, like the project's name. From c76689c93de5d6d477c090eec27394191e64dd20 Mon Sep 17 00:00:00 2001 From: Vladimir <48120135+izmalk@users.noreply.github.com> Date: Tue, 14 Jan 2025 12:05:34 +0000 Subject: [PATCH 7/8] Fixing another inclusive lang check finding Removing link to fix the inclusive language language check --- docs/content/edit.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/edit.rst b/docs/content/edit.rst index 2d1ad953..78de7f31 100644 --- a/docs/content/edit.rst +++ b/docs/content/edit.rst @@ -6,7 +6,7 @@ Edit content The landing page is stored in the :file:`docs/index.rst` file while the rest of the pages are stored in the :file:`docs/content/` folder by default. -The Navigation Menu structure is set by ``.. toctree::`` [directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree). These directives define the hierarchy of included content throughout the documentation. +The Navigation Menu structure is set by ``.. toctree::`` directives. These directives define the hierarchy of included content throughout the documentation. The :file:`index.rst` page's ``toctree`` block contains the top level Navigation Menu. To add a new page to the documentation: From e93cc44a29a62e66e6277feca584908323d55249 Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Wed, 15 Jan 2025 17:44:05 +0000 Subject: [PATCH 8/8] Update docs/content/enable.rst Co-authored-by: Michael Park --- docs/content/enable.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/enable.rst b/docs/content/enable.rst index de8151e1..c7c397b6 100644 --- a/docs/content/enable.rst +++ b/docs/content/enable.rst @@ -5,7 +5,7 @@ Copy the starter pack Make sure to copy all required starter pack files to initialise a new documentation set: -#. Clone the `Starter pack `_ repository to a temporary local folder +#. Clone the `Starter pack `_ repository locally. #. Copy the following folders and files from the starter pack temporary folder to the repository where you want your documentation, placing them at the same relative paths: - :file:`docs` -- your documentation folder. Original content includes initial documentation pages (you are reading one of them) and internal Sphinx files