docs: add info to support nested workflow, part 1

Signed-off-by: Minae Lee <[email protected]>

sp-docs/docs/automatic_checks_accessibility.rst

@@ -14,11 +14,11 @@ It is configured to use the `Web Content Accessibility Guidelines (WCAG) 2.2`_,
 Install prerequisite software
 -----------------------------
 
-``Pa11y`` must be installed through ``npm``::
+``Pa11y`` must be installed through ``npm``. If you need to install ``npm``, run the following command from any location on your system::
 
    sudo apt install npm
 
-To install ``Pa11y``:
+Once ``npm`` is installed, install ``Pa11y`` by running this command from within your documentation folder.
 
 .. code-block:: bash
 
@@ -27,13 +27,15 @@ To install ``Pa11y``:
 Run the accessibility check
 ---------------------------
 
+Run the following command from within your documentation folder.
+
 Look for accessibility issues in rendered documentation::
 
    make pa11y
 
 Configure the accessibility check
 ---------------------------------
 
-The :file:`pa11y.json` file in the :file:`.sphinx` directory provides basic defaults.
+The :file:`pa11y.json` file in the :file:`.sphinx` folder provides basic defaults.
 
 To browse the available settings and options, see ``Pa11y``'s `README <Pa11y readme_>`_ on GitHub.

sp-docs/docs/automatic_checks_inclusivelanguage.rst

@@ -8,6 +8,8 @@ The inclusive language check uses `woke`_ to check for violations of inclusive l
 Install prerequisite software
 -----------------------------
 
+The following two commands can be run from any location on your system.
+
 To install ``woke``, you need ``snap``::
 
    sudo apt install snapd
@@ -21,16 +23,17 @@ To install ``woke``:
 Run the inclusive language check
 --------------------------------
 
+Run the following command from within your documentation folder.
+
 Ensure the documentation uses inclusive language::
 
    make woke
 
 Configure the inclusive language check
 --------------------------------------
 
-By default, the inclusive language check is applied only to |RST| files located
-under the documentation directory (usually :file:`docs`).
-To check Markdown files, for example, or to use a location other than the :file:`docs` sub-tree, you must override the ``ALLFILES`` variable in :file:`Makefile.sp` (see :ref:`Makefile`).
+By default, the inclusive language check is applied only to |RST| files located in the documentation folder (usually :file:`docs/`).
+To check Markdown files, for example, or to use a location other than the :file:`docs/` sub-tree, you must override the ``ALLFILES`` variable in :file:`Makefile.sp` (see :ref:`Makefile`).
 
 You can find more information about available options in the `woke User Guide`_.
 

sp-docs/docs/automatic_checks_links.rst

@@ -8,6 +8,8 @@ The link check uses Sphinx to access the links in the documentation output and v
 Run the link check
 ------------------
 
+Run the following command from within your documentation folder.
+
 Validate links within the documentation::
 
    make linkcheck

sp-docs/docs/automatic_checks_spelling.rst

@@ -9,6 +9,8 @@ It ignores code (both code blocks and inline code) and URLs (but it does check t
 Run the spelling check
 ----------------------
 
+Run the following commands from within your documentation folder.
+
 Ensure there are no spelling errors in the documentation::
 
   make spelling

sp-docs/docs/automatic_checks_styleguide.rst

@@ -9,19 +9,21 @@ The starter pack includes a method to run the `Vale`_ documentation linter confi
 Run the style guide linting
 ---------------------------
 
+Run the following commands from within your documentation folder.
+
 Check documentation with Vale::
 
    make vale
 
-Vale can run against individual files, directories, or globs.
+Vale can run against individual files, folders, or globs.
 To set a specific target::
 
     make vale TARGET=example.file
-    make vale TARGET=example-directory
+    make vale TARGET=example-folder
 
 .. note::
 
-    Running Vale against a directory will also run against subfolders.
+    Running Vale against a folder will also run against its subfolders.
 
 You can use wildcards to run against all files matching a string, or an extension.
 

sp-docs/docs/build.rst

@@ -3,9 +3,13 @@
 Build and preview
 =================
 
-The starter pack provides make commands to build and view the documentation.
+The starter pack provides :command:`make` commands to build and view the documentation.
+
 All these commands will automatically set up the Python environment if it isn't set up yet.
 
+.. important::
+   Run these commands from within your documentation folder.
+
 .. _build-docs:
 
 Build the documentation
@@ -15,7 +19,7 @@ To build the documentation, run the following command::
 
   make html
 
-This command installs the required tools and renders the output to the :file:`_build/` directory in your documentation directory.
+This command installs the required tools and renders the output to the :file:`_build/` folder in your documentation folder.
 
 .. important::
    When you run :command:`make html` again, it updates the documentation for changed files only.

sp-docs/docs/makefile.rst

@@ -3,19 +3,20 @@
 Integrate the Makefiles
 =======================
 
-The starter pack contains two Makefiles: :file:`Makefile` and :file:`Makefile.sp`.
+The starter pack contains two Makefiles, located in the documentation folder: :file:`Makefile` and :file:`Makefile.sp`.
 
 :file:`Makefile.sp` implements the targets provided by the starter pack.
-You should keep it up-to-date with recent changes to the starter pack; therefore, avoid doing updates to the file.
+You should keep it up to date with recent changes to the starter pack; therefore, avoid making updates to this file.
 (If you need updates, consider contributing them to the starter pack!)
 
 You can use :file:`Makefile` to add custom targets or different target names.
 
-If you want to integrate the starter pack targets into the main Makefile of your project, you can do so with a command similar to the following::
+Your project might contain a main Makefile in its root folder (usually the parent of the documentation folder), used for building the project rather than the documentation. If you want to integrate the starter pack targets into your project's main Makefile, you can use a command similar to the following::
 
   doc-%:
   	cd docs && $(MAKE) -f Makefile.sp sp-$* ALLFILES='*.md **/*.md'
 
 This example will create targets prefixed with ``doc-`` (for example, ``doc-html`` and ``doc-serve``).
-When calling these targets, they switch to the documentation folder (``docs`` in this case) and run the corresponding ``sp-*`` targets from :file:`Makefile.sp`.
-In addition, the ``ALLFILES`` variable is overridden with a different set of files (this is needed for the :ref:`automatic-checks-inclusivelanguage`).
+When calling :command:`make` with one of these targets from the project's root folder, they switch to the documentation folder (``docs`` in this case) and run the corresponding ``sp-*`` targets from :file:`Makefile.sp`.
+
+In addition, the ``ALLFILES`` variable is overridden with a different set of files, which is needed for the :ref:`automatic-checks-inclusivelanguage`.

sp-docs/docs/prereqs.rst

@@ -19,13 +19,13 @@ Python environment
 
 The Python prerequisites from the :file:`.sphinx/requirements.txt` file are automatically installed when you build the documentation.
 
-If you want to install them manually, you can run the following command::
+If you want to install them manually, you can run the following command from within your documentation folder::
 
    make install
 
-This command creates a virtual environment (:file:`.sphinx/venv`) and installs dependency software within it.
+This command creates a virtual environment (:file:`.sphinx/venv/`) and installs dependency software within it.
 
-If you want to remove the installed Python packages (for example, to enforce a re-installation), run the following command::
+If you want to remove the installed Python packages (for example, to enforce a re-installation), run the following command from within your documentation folder::
 
   make clean
 

sp-docs/docs/quickstart.rst

@@ -14,7 +14,7 @@ For more detailed information, see the other sections of the starter pack docume
 
    See :ref:`enable` for detailed information on what the script does.
 
-#. Enter the documentation folder (the folder you specified when running the script) and build the documentation with the following command::
+#. 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
 

sp-docs/docs/rtd.rst

@@ -10,8 +10,10 @@ In general, after enabling the starter pack for your documentation, follow these
 1. Make sure your documentation :ref:`builds without errors or warnings <build-clean>`.
 #. Log into Read the Docs.
 #. Use the `manual import`_ to create a project.
-#. If your documentation is not on the root level but in a documentation folder, you must specify the path to the :file:`.readthedocs.yaml` file for your build.
-   You do this by navigating to :guilabel:`Admin` > :guilabel:`Settings` and specifying the path under "Path for ``.readthedocs.yaml``".
+#. Specify the path to the :file:`.readthedocs.yaml` file for your build.
+   To do this, navigate to :guilabel:`Admin` > :guilabel:`Settings` and specify the path under "Path for ``.readthedocs.yaml``".
+
+   For example, if your documentation folder is :file:`docs/`, specify the path as ``docs/readthedocs.yaml``.
 
 After this initial setup, your documentation should build successfully.
 If you get any errors, check the build log for indications on what the problem is.