Merge pull request #319 from izmalk/manual-docs-upd-deinit

[DOCPR-1022] Document manual workflow

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.
+Configuration for a starter pack based documentation is set in the :file:`docs/conf.py` Sphinx configuration 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 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 configuration to adapt the documentation to your project.
+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.
 
 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 (: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.
 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'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 should always check 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.
@@ -50,19 +53,20 @@ 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 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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,47 @@ 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 included by default:
 
-The following extensions are always included:
+* ``canonical_sphinx``
+* ``sphinxcontrib.cairosvgconverter``
+* ``sphinx_last_updated_by_git``
 
-- :literalref:`myst_parser <https://myst-parser.readthedocs.io/en/latest/>`
-- :literalref:`sphinxcontrib.jquery <https://github.com/sphinx-contrib/jquery/>`
+The `canonical_sphinx` extension is required for the starter pack.
+It automatically enables and sets default configurations for the following extensions:
 
-The following extensions are included with the ``[full]`` optional install of canonical-sphinx:
+* ``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``
 
-- :literalref:`sphinx-design <https://sphinx-design.readthedocs.io/en/latest/>`
-- :literalref:`sphinx_copybutton <https://sphinx-copybutton.readthedocs.io/en/latest/>`
-- :literalref:`sphinx_tabs.tabs <https://sphinx-tabs.readthedocs.io/en/latest/>`
-- :literalref:`sphinx_reredirects <https://documatt.gitlab.io/sphinx-reredirects/>`
-- :literalref:`sphinxext.opengraph <https://sphinxext-opengraph.readthedocs.io/en/latest/>`
-- :literalref:`canonical-sphinx-extensions <https://github.com/canonical/canonical-sphinx-extensions>` (``youtube-links``, ``related-links``, ``custom-rst-roles``, and ``terminal-output``)
-- :literalref:`notfound.extension <https://sphinx-notfound-page.readthedocs.io/en/latest/>`
+To add new extensions needed for your documentation set, add them to the ``extensions`` parameter in :file:`docs/conf.py`.
+.. info::
 
-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.
+    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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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,16 +146,15 @@ 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 <Furo documentation_>`_), 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.
+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:
 

docs/content/edit.rst

@@ -0,0 +1,49 @@
+.. _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 by default.
+
+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:    
+
+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 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 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 </content/reference>`.

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 <https://github.com/canonical/sphinx-docs-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:
 
-The starter pack provides a shell script that updates and copies the starter pack files to the selected location.
+   - :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 inclusive language check
+   - :file:`.github/workflows/*-checks.yml` -- documentation tests
 
-.. 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 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. 

docs/content/quickstart.rst

@@ -1,65 +1,49 @@
 .. _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 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`.
 
-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.
+Clone the `Starter pack <https://github.com/canonical/sphinx-docs-starter-pack>`_ repository to a temporary local folder.
 
-#. 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.
+Copy the following folders and files preserving their paths from the starter pack to the repository you want your documentation to be:
 
-   See :ref:`enable` for detailed information on what the script does.
+   - :file:`docs`
+   - :file:`.readthedocs.yaml`
+   - :file:`.wokeignore`
+   - :file:`.github/workflows/*-checks.yml`
 
-#. Enter the documentation folder (the folder you specified when running the script, such as :file:`docs/`) and build the documentation with the following command::
 
-     make run
+Build and run the local server
+==============================
 
-   This command creates a virtual environment, installs the Python dependencies, builds the documentation, and serves it on :literalref:`http://127.0.0.1:8000/`.
+To build HTML documentation the prerequisites are:
 
-   See :ref:`build` for detailed information on different commands for building and viewing the documentation.
+* ``make`` 
+* ``python3``
+* ``python3-venv``
+* ``python3-pip`` 
 
-#. 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.
+In :file:`docs`, run::
 
-#. 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:
+    make run
 
-   .. code-block:: rest
+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/`.
 
-      Reference
-      =========
+The server watches the source files, including :file:`docs/conf.py`, and rebuilds automatically on changes.
 
-   .. 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:
+Configure
+=========
 
-      .. code-block:: Markdown
+Work through the settings in :file:`docs/conf.py`. Most parameters can be left with the default values as they can be changed later.
 
-         # Reference
+Update content
+==============
 
-#. Open :file:`index.rst`.
-
-   At the bottom of this file, add a 3-space-indented line containing ``Reference <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:
-
-   .. code-block:: rest
-
-      .. toctree::
-         :hidden:
-         :maxdepth: 2
-
-         self
-         Reference <reference>
-
-   .. 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 <reference>``.
-
-#. Check :literalref:`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.
-
-See :ref:`guidance` for links to more detailed information about |RST| and Markdown/MyST.
+The landing page is :file:`docs/index.rst`. Other pages are under :file:`docs/content`.

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