Fix docs build breaking errors

CONTRIBUTING.rst

@@ -178,10 +178,8 @@ right before you open a pull request. And with that step, it's time to
 start hacking on Salt!
 
 
-.. _imagemagick-setup:
+Set up imagemagick
-
+------------------
-Set up ``imagemagick``
-----------------------
 One last prerequisite is to have ``imagemagick`` installed, as it is required
 by Sphinx for generating the HTML documentation.
 
@@ -267,7 +265,7 @@ Before approving code contributions, Salt requires:
 Documentation fixes just require correct documentation.
 
 What if I don't write tests or docs?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+------------------------------------
 
 If you aren't into writing documentation or tests, we still welcome your
 contributions! But your PR will be labeled ``Needs Testcase`` and
@@ -282,14 +280,65 @@ and Thursday morning, Central Time. If you'd like specific help with
 tests, bring them to the clinic. If no community members need help, you
 can also just watch tests written in real time.
 
-.. _docs-building:
 
 Documentation
 -------------
 
 Salt uses both docstrings, as well as normal reStructuredText files in
 the ``salt/doc`` folder for documentation. Sphinx is used to generate the
-documentation, and does require :ref:`setting up imagemagick on your OS.<imagemagick-setup>`
+documentation, and does require ``imagemagick``. See `Set up imagemagick`_ for
+more information.
+
+Before submitting a documentation PR, it helps to first build the Salt docs 
+locally on your machine and preview them. Local previews helps you:
+
+- Debug potential documentation output errors before submitting a PR.
+- Saves you time by not needing to use the Salt CI/CD test suite to debug, which takes
+  more than 30 minutes to run on a PR.
+- Ensures the final output looks the way you intended it to look.
+
+To set up your local environment to preview the core Salt and module 
+documentation:
+
+#. Install the documentation dependencies. For example, on Ubuntu:
+
+   ::
+   
+       sudo apt-get update
+
+       sudo apt-get install -y enchant-2 git gcc imagemagick make zlib1g-dev libc-dev libffi-dev g++ libxml2 libxml2-dev libxslt-dev libcurl4-openssl-dev libssl-dev libgnutls28-dev xz-utils inkscape
+
+#. Navigate to the folder where you store your Salt repository and remove any 
+   `.nox` directories that might be in that folder:
+
+   ::
+   
+       rm -rf .nox
+
+#. Install `pyenv` for the version of Python needed to run the docs. As of the 
+   time of writing, the Salt docs theme is not compatible with Python 3.10, so
+   you'll need to run 3.9 or earlier. For example:
+
+   ::
+   
+       pyenv install 3.7.15
+       pyenv virtualenv 3.7.15 salt-docs
+       echo 'salt-docs' > .python-version
+
+#. Activate `pyenv` if it's not auto-activated:
+
+   ::
+   
+       pyenv exec pip install -U pip setuptools wheel
+
+#. Install `nox` into your pyenv environment, which is the utility that will
+   build the Salt documentation:
+
+   ::
+   
+       pyenv exec pip install nox
+
+
 Since we use ``nox``, you can build your docs and view them in your browser
 with this one-liner:
 
@@ -297,9 +346,9 @@ with this one-liner:
 
    python -m nox -e 'docs-html(compress=False, clean=False)'; cd doc/_build/html; python -m webbrowser http://localhost:8000/contents.html; python -m http.server
 
-The first time this will take a while because there are a *lot* of
+The first time you build the docs, it will take a while because there are a 
-modules. Maybe you should go grab some dessert if you already finished
+*lot* of modules. Maybe you should go grab some dessert if you already finished
-that sandwich. But once Sphinx is done building the docs, python should
+that sandwich. But once nox and Sphinx are done building the docs, python should
 launch your default browser with the URL
 http://localhost:8000/contents.html. Now you can navigate to your docs
 and ensure your changes exist. If you make changes, you can simply run
@@ -312,9 +361,18 @@ this:
 And then refresh your browser to get your updated docs. This one should
 be quite a bit faster since Sphinx won't need to rebuild everything.
 
+Alternatively, you could build the docs on your local machine and then preview
+the build output. To build the docs locally:
+
+::
+
+    pyenv exec nox -e 'docs-html(compress=False, clean=True)'
+
+The output from this command will put the preview files in: ``doc > _build > html``.
+
 If your change is a docs-only change, you can go ahead and commit/push
 your code and open a PR. You can indicate that it's a docs-only change by
-adding ``[Documentation]`` to the title of your PR. Otherwise you'll
+adding ``[Documentation]`` to the title of your PR. Otherwise, you'll
 want to write some tests and code.
 
 

doc/_incl/requisite_incl.rst

@@ -1,9 +1,10 @@
 **Before continuing** make sure you have a working Salt installation by
-following the :ref:`installation` and the
+following the instructions in the 
-:ref:`configuration <configuring-salt>` instructions.
+`Salt install guide <https://docs.saltproject.io/salt/install-guide/en/latest/>`_.
 
 .. admonition:: Stuck?
 
-    There are many ways to :ref:`salt-community` including our
+    The Salt Project community can help offer advice and help troubleshoot 
-    `mailing list <https://groups.google.com/forum/#!forum/salt-users>`_
+    technical issues as you're learning about Salt. One of the best places to
-    and our `IRC channel <https://web.libera.chat/#salt>`_ #salt.
+    talk to the community is on the 
+    `Salt Project Slack workspace <https://saltstackcommunity.slack.com/>`_.

doc/contents.rst

@@ -10,7 +10,7 @@ Salt Table of Contents
     topics/about_salt_project
     topics/index
     topics/salt_system_architecture
-    topics/contributing
+    topics/contributing-guide
     topics/installation/index
     topics/configuration/index
     topics/using_salt

doc/topics/contributing-guide.rst

@@ -1,3 +1,3 @@
-.. _contributing:
+.. _contributing-import:
 
 .. include:: ../../CONTRIBUTING.rst

doc/topics/development/conventions/documentation.rst

@@ -1,298 +1,11 @@
 .. _salt-docs:
 
 ==========================
-Writing Salt Documentation
+Writing Salt documentation
 ==========================
 
-Salt's documentation is built using the `Sphinx`_ documentation system. It can
+For the latest information about writing Salt documentation, see:
-be built in a large variety of output formats including HTML, PDF, ePub, and
-manpage.
 
-All the documentation is contained in the main Salt repository. Speaking
+* `Salt docs contributing guide <https://saltstack.gitlab.io/open/docs/docs-hub/topics/contributing.html>`_
-broadly, most of the narrative documentation is contained within the
+* `Salt rST guide <https://saltstack.gitlab.io/open/docs/docs-hub/topics/rst-guide.html>`_
-:blob:`doc` subdirectory and most of the reference and API documentation is
+* `Salt style guide <https://saltstack.gitlab.io/open/docs/docs-hub/topics/style-guide.html>`_
-written inline with Salt's Python code and extracted using a Sphinx extension.
-
-.. _`Sphinx`: https://www.sphinx-doc.org/en/master/
-
-
-.. _docs-style:
-
-Style
-=====
-
-The Salt project recommends the `IEEE style guide`_ as a general reference for
-writing guidelines. Those guidelines are not strictly enforced but rather serve
-as an excellent resource for technical writing questions. The `NCBI style
-guide`_ is another very approachable resource.
-
-.. _`IEEE style guide`: https://mentor.ieee.org/myproject/Public/mytools/draft/styleman.pdf
-.. _`NCBI style guide`: https://www.ncbi.nlm.nih.gov/books/NBK993/
-
-Point-of-view
--------------
-
-Use third-person perspective and avoid "I", "we", "you" forms of address.
-Identify the addressee specifically e.g., "users should", "the compiler does",
-etc.
-
-Active voice
-------------
-
-Use active voice and present-tense. Avoid filler words.
-
-Title capitalization
---------------------
-
-Document titles and section titles within a page should follow normal sentence
-capitalization rules. Words that are capitalized as part of a regular sentence
-should be capitalized in a title and otherwise left as lowercase. Punctuation
-can be omitted unless it aids the intent of the title (e.g., exclamation points
-or question marks).
-
-For example:
-
-.. code-block:: restructuredtext
-
-    This is a main heading
-    ======================
-
-    Paragraph.
-
-    This is an exciting sub-heading!
-    --------------------------------
-
-    Paragraph.
-
-
-.. _docs-modules:
-
-Serial Commas
--------------
-
-According to Wikipedia: In English punctuation, a serial comma or series comma
-(also called Oxford comma and Harvard comma) is a comma placed immediately
-before the coordinating conjunction (usually "and", "or", or "nor") in a series of
-three or more terms. For example, a list of three countries might be punctuated
-either as "France, Italy, and Spain" (with the serial comma), or as "France,
-Italy and Spain" (without the serial comma)."
-
-When writing a list that includes three or more items, the serial comma should
-always be used.
-
-Documenting modules
-===================
-
-Documentation for Salt's various module types is inline in the code. During the
-documentation build process it is extracted and formatted into the final HTML,
-PDF, etc format.
-
-Inline documentation
---------------------
-
-Python has special multi-line strings called docstrings as the first element in
-a function or class. These strings allow documentation to live alongside the
-code and can contain special formatting. For example:
-
-.. code-block:: python
-
-    def my_function(value):
-        """
-        Upper-case the given value
-
-        Usage:
-
-        .. code-block:: python
-
-            val = 'a string'
-            new_val = myfunction(val)
-            print(new_val) # 'A STRING'
-
-        :param value: a string
-        :return: a copy of ``value`` that has been upper-cased
-        """
-        return value.upper()
-
-Specify a release for additions or changes
-------------------------------------------
-
-New functions or changes to existing functions should include a marker that
-denotes what Salt release will be affected. For example:
-
-.. code-block:: python
-
-    def my_function(value):
-        """
-        Upper-case the given value
-
-        .. versionadded:: 2014.7.0
-
-        <...snip...>
-        """
-        return value.upper()
-
-For changes to a function:
-
-.. code-block:: python
-
-    def my_function(value, strip=False):
-        """
-        Upper-case the given value
-
-        .. versionchanged:: 2016.3.0
-            Added a flag to also strip whitespace from the string.
-
-        <...snip...>
-        """
-        if strip:
-            return value.upper().strip()
-        return value.upper()
-
-Adding module documentation to the index
-----------------------------------------
-
-Each module type has an index listing all modules of that type. For example:
-:ref:`all-salt.modules`, :ref:`all-salt.states`, :ref:`all-salt.renderers`.
-New modules must be added to the index manually.
-
-1.  Edit the file for the module type:
-    :blob:`execution modules <doc/ref/modules/all/index.rst>`,
-    :blob:`state modules<doc/ref/states/all/index.rst>`,
-    :blob:`renderer modules <doc/ref/renderers/all/index.rst>`, etc.
-
-2.  Add the new module to the alphabetized list.
-
-3.  :ref:`Build the documentation <docs-building>` which will generate an ``.rst``
-    file for the new module in the same directory as the ``index.rst``.
-
-4.  Commit the changes to ``index.rst`` and the new ``.rst`` file and send a
-    pull request.
-
-
-.. _docs-ref:
-
-Cross-references
-================
-
-The Sphinx documentation system contains a wide variety of cross-referencing
-capabilities.
-
-
-.. _docs-ref-glossary:
-
-Glossary entries
-----------------
-
-Link to :ref:`glossary entries <glossary>` using the `term role`_. A
-cross-reference should be added the first time a Salt-specific term is used in
-a document.
-
-.. _`term role`: https://www.sphinx-doc.org/en/master/glossary.html#term-role
-
-.. code-block:: restructuredtext
-
-    A common way to encapsulate master-side functionality is by writing a
-    custom :term:`Runner Function`. Custom Runner Functions are easy to write.
-
-
-.. _docs-ref-index:
-
-Index entries
--------------
-
-Sphinx automatically generates many kinds of index entries, but it is
-occasionally useful to manually add items to the index.
-
-One method is to use the `index directive`_ above the document or section that
-should appear in the index.
-
-.. _`index directive`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html?highlight=index%20directive#index-generating-markup
-
-.. code-block:: restructuredtext
-
-    .. index:: ! Event, event bus, event system
-        see: Reactor; Event
-
-Another method is to use the `index role`_ inline with the text that should
-appear in the index. The index entry is created and the target text is left
-otherwise intact.
-
-.. _`index role`: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#role-index
-
-.. code-block:: restructuredtext
-
-    Information about the :index:`Salt Reactor`
-    -------------------------------------------
-
-    Paragraph.
-
-
-.. _docs-ref-docs:
-
-Documents and sections
-----------------------
-
-Each document should contain a unique top-level label of the form:
-
-.. code-block:: restructuredtext
-
-    .. _my-page:
-
-    My page
-    =======
-
-    Paragraph.
-
-Unique labels can be linked using the `ref role`_. This allows cross-references
-to survive document renames or movement.
-
-.. code-block:: restructuredtext
-
-    For more information see :ref:`my-page`.
-
-Note, the ``:doc:`` role should *not* be used to link documents together.
-
-.. _`ref role`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
-
-
-.. _docs-ref-modules:
-
-Modules
--------
-
-Cross-references to Salt modules can be added using Sphinx's Python domain
-roles. For example, to create a link to the :py:func:`test.ping
-<salt.modules.test.ping>` function:
-
-.. code-block:: restructuredtext
-
-    A useful execution module to test active communication with a minion is the
-    :py:func:`test.ping <salt.modules.test.ping>` function.
-
-Salt modules can be referenced as well:
-
-.. code-block:: restructuredtext
-
-    The :py:mod:`test module <salt.modules.test>` contains many useful
-    functions for inspecting an active Salt connection.
-
-The same syntax works for all modules types:
-
-.. code-block:: restructuredtext
-
-    One of the workhorse state module functions in Salt is the
-    :py:func:`file.managed <salt.states.file.managed>` function.
-
-
-.. _docs-ref-settings:
-
-Settings
---------
-
-Individual settings in the Salt Master or Salt Minion configuration files are
-cross-referenced using two custom roles, ``conf_master``, and ``conf_minion``.
-
-.. code-block:: restructuredtext
-
-    The :conf_minion:`minion ID <id>` setting is a unique identifier for a
-    single minion.

doc/topics/tutorials/states_pt4.rst

@@ -209,8 +209,9 @@ can be found on GitHub in the `saltstack-formulas`_ collection of repositories.
 .. _`saltstack-formulas`: https://github.com/saltstack-formulas
 
 If you have any questions, suggestions, or just want to chat with other people
-who are using Salt, we have a very :ref:`active community <salt-community>`
+who are using Salt, we have a very active community and we'd love to hear from 
-and we'd love to hear from you.
+you. One of the best places to talk to the community is on the 
+`Salt Project Slack workspace <https://saltstackcommunity.slack.com/>`_.
 
 In addition, by continuing to the :ref:`Orchestrate Runner <orchestrate-runner>` docs,
 you can learn about the powerful orchestration of which Salt is capable.