docs: add info to support nested workflow, part 1 (#313)

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

docs/content/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.

docs/content/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`_.
 

docs/content/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

docs/content/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

docs/content/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.
 

docs/content/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.

docs/content/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
 

docs/content/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
 

docs/content/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 your project is hosted from a public repository.
 If you get any errors, check the build log for indications on what the problem is.