Move links:x to documentation/index & documentation/troubleshooting

Author: ArBridgeman

doc/user_guide/customization.rst

@@ -3,19 +3,6 @@ Customization
 
 .. _plugins:
 
-Nox Tasks `links:x`
----------------------
-
-PTB offers two nox sessions to check hyperlinks in your documentation:
- * `links:list` - List all the links within the documentation
- * `links:check` - Checks whether all links in the documentation are accessible
-
-`links:check` is run in the CI `checks.yml`. If this step fails in the CI, it will cause
-the build to break. Please check the output & manually resolve the issues. There might
-be some cases where you need to update your `doc/conf.py` with specific values for the allowed
-options for the [Linkcheck Builder](https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder).
-
-
 Nox Task Plugins
 ----------------
 

doc/user_guide/features/documentation/index.rst

@@ -10,6 +10,27 @@ Building documentation
     troubleshooting
 
 In the PTB, we use sphinx to build and validate the contents of a project's
+documentation. All documentation is provided in the ``doc`` directory, primarily as
+`rst` files. The ``doc/conf.py`` acts as the configuration file for building the
 documentation.
 
-< table>
+Many of the nox session checks are executed in the ``checks.yml`` so that alterations
+in the documentation can be directly attributed (and, if needed, fixed) in the relevant
+PR. The final building & serving of the documentation happens in the ``gh-pages.yml``.
+
++--------------------------+------------------+----------------------------------------+
+| Nox session              | CI Usage         | Action                                 |
++==========================+==================+========================================+
+| ``docs:build``           | ``checks.yml``   | Builds the documentation               |
++--------------------------+------------------+----------------------------------------+
+| ``docs:clean``           | No               | Removes the documentation build folder |
++--------------------------+------------------+----------------------------------------+
+| ``docs:multiversion``    | ``gh-pages.yml`` | Builds the multiversion documentation  |
++--------------------------+------------------+----------------------------------------+
+| ``docs:open``            | No               | Opens the built documentation          |
++--------------------------+------------------+----------------------------------------+
+| ``links:check``          | ``checks.yml``   | Checks if all links in the             |
+|                          |                  | documentation are accessible           |
++--------------------------+------------------+----------------------------------------+
+| ``links:list``           | No               | Lists all links in the documentation   |
++--------------------------+------------------+----------------------------------------+

doc/user_guide/features/documentation/troubleshooting.rst

@@ -60,3 +60,11 @@ of the multiversion documentation, it is likely due to the fact that the unavail
 documentation for those versions was not in a compatible format. In other words, there
 had not, for those missing versions, been a compatible setup of a Sphinx-based
 documentation.
+
+``links:check`` breaks CI build
+-------------------------------
+``links:check`` is run in the CI ``checks.yml``. If this step fails in the CI, it will
+cause the build to break. Please check the output & manually resolve the issues. There
+might be some cases where you need to update your ``doc/conf.py`` with specific values
+for the allowed options for the
+`Linkcheck Builder <https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder>`__.