Documentation/512 consolidate documentation (#513)

* sphinx-multiversion to building_documentation.rst

* Move FAQ docs to documentation/troubleshooting.rst

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

* Remove unneeded steps as in cookiecutter template & .gitignore there

* Write as conf.py included in cookiecutter project template, so don't need to provide specific config instructions here

* Move configuration information into documentation/index and reference in getting_started

* Add changelog entry

* Improve introduction of documentation per review

Co-authored-by: Christoph Kuhnke <christoph.kuhnke@exasol.com>

* Sections need actual numbers not #s per review

* Update description to make clearer GitHub workflows & nicer content per review

Co-authored-by: Christoph Kuhnke <christoph.kuhnke@exasol.com>

* Identify workflows & actions & be more explicit per review

Co-authored-by: Christoph Kuhnke <christoph.kuhnke@exasol.com>

* Alter comment per review but fix with apostrophe applied

* Add sphinx redirect

---------

Co-authored-by: Christoph Kuhnke <christoph.kuhnke@exasol.com>

Author: ArBridgeman

doc/changes/unreleased.md

@@ -1 +1,5 @@
 # Unreleased
+
+## Documentation
+
+* #512: Consolidated and added to deploying documentation pages

doc/conf.py

@@ -88,5 +88,6 @@
 linkcheck_allowed_redirects = {
     # All HTTP redirections from the source URI to
     # the canonical URI will be treated as "working".
-    r"https://github\.com/.*": r"https://github\.com/login*"
+    r"https://github\.com/.*": r"https://github\.com/login*",
+    r"https://www.sphinx-doc\.org/.*": r"https://www.sphinx-doc\.org/en/master/.*",
 }

doc/developer_guide/modules/modules.rst

@@ -4,6 +4,5 @@ Modules
 .. toctree::
     :maxdepth: 2
 
-    sphinx/sphinx
     nox
     nox_tasks

doc/developer_guide/modules/sphinx/sphinx.rst

@@ -17,54 +17,6 @@ There are several methods to configure your shell:
     2. For a general setup: :code:`export PYTHONPATH=`pwd``
     3. Alternatively, tools like `direnv <https://direnv.net>`_ can be used.
 
-.. _faq_duplicated_label_error:
-
-Duplicated label error when building documentation
---------------------------------------------------
-
-Similar error to :code:`Warning, treated as error: integration-test-docker-environment/doc/changes/changes_0.10.0.md:5:duplicate label summary, other instance in integration-test-docker-environment/doc/changes/changes_0.1.0.md'`, might be caused by sphinx extension `sphinx.ext.autosectionlabel`. Try to remove this extension in `doc/conf.py`.
-
-
-.. _faq_multiversion_build_warnings:
-
-Warning while building multiversion documentation
---------------------------------------------------
-When running ``nox -s docs:multiversion``, I receive the following warnings during the build:
-
-.. code-block::
-
-    WARNING: unknown config value 'smv_metadata_path' in override, ignoring
-    WARNING: unknown config value 'smv_current_version' in override, ignoring
-
-If you receive the warnings above, it is very likely that the multiversion extension is not configured in your Sphinx configuration (``conf.py``). Try adding it to your configuration and rerun the build.
-
-.. code-block:: python
-
-    extensions = [
-        ...,
-        ...,
-        "exasol.toolbox.sphinx.multiversion",
-    ]
-
-
-.. _faq_multiversion_selection_missing:
-
-Missing Version Selection Box in Multiversion Documentation
-------------------------------------------------------------
-
-I have run ``nox -s docs:multiversion``, but I still do not see any version selection box in the upper right corner before the GitHub symbol.
-
-This is likely due to :ref:`faq_multiversion_build_warnings`
-
-
-.. _faq_multiversion_limited_versions:
-
-Limited Previous Versions in Multiversion Documentation
--------------------------------------------------------
-
-If not all previous versions of the project are available via the version selection box of the multiversion documentation, it is likely due to the fact that the unavailable documentation for those versions was not in a compatible format (there hasn't been a compatible setup of a Sphinx-based documentation).
-
-
 .. _faq_failing_format_check:
 
 Format Still Fails After Running ``project:fix``

doc/faq.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/customization.rst

@@ -0,0 +1,70 @@
+.. _deploying_documentation:
+
+Deploying documentation
+=======================
+
+.. toctree::
+    :maxdepth: 2
+
+    multiversion
+    troubleshooting
+
+The PTB uses ref:`sphinx <https://www.sphinx-doc.org/>`__ to build and validate the contents
+of your project's documentation. PTB expects the project's documentation in directory ``doc``,
+primarily as ``rst`` files. The ``doc/conf.py`` acts as the configuration file for building the
+documentation.
+
+GitHub workflow ``checks.yml`` also runs the checks for the documention.
+This enables updating and fixing the documentation together with other changes in the same pull request.
+The final building & serving of the documentation happens in GitHub workflow ``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   |
++--------------------------+------------------+----------------------------------------+
+
+.. _documentation_configuration:
+
+Configuration
++++++++++++++
+
+``doc/conf.py``
+^^^^^^^^^^^^^^^
+The PTB's cookiecutter project template already provides a file ``doc/conf.py`` with
+default content. If your project needs adjustment, please refer to:
+
+* the `general sphinx documentation <https://www.sphinx-doc.org/en/master/>`__.
+* specifically to the `Linkcheck Builder <https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder>`__
+  for ``links:check`` and ``links:list``.
+
+``gh-pages.yml``
+^^^^^^^^^^^^^^^^
+GitHub workflow ``gh-pages.yml`` uses actions ``upload-pages-artifact`` and ``deploy-pages``.
+In order to properly deploy your generated documentation, you will need to manually
+reconfigure the GitHub Pages settings for the repo:
+
+#. Go to the affected repo's GitHub page
+#. Select 'Settings'
+#. Scroll down & select 'Pages'
+#. Within the 'Build and deployment' section, change 'Source' to 'GitHub Actions'.
+
+You also need to configure settings for the `github-pages` environment:
+
+#. Go to the affected repo's GitHub page
+#. Select 'Settings'
+#. Scroll down & select 'Environment'
+#. Click on 'github-pages'
+#. In the 'Deployment branches and tags', click 'Add deployment branch or tag rule'
+#. Select 'Ref type' to be 'Tag' and set the 'Name pattern' to `[0-9]*.[0-9]*.[0-9]*` (or whatever matches that repo's tags)

doc/user_guide/features/documentation/index.rst

@@ -0,0 +1,34 @@
+sphinx-multiversion
+===================
+
+The ``sphinx-multiversion`` extension is a modified copy of
+`sphinx-contrib/multiversion <https://github.com/sphinx-contrib/multiversion>`__.
+This copy was taken from version :code:`0.24.0`.
+
+It has been modified to work with Exasol's integration projects, which often require a
+specific project structure and layout. Additionally, it is designed to be used with an
+HTML theme that supports displaying and selecting multiple versions if the `versions`
+variable is set in the HTML context of sphinx. As of this writing, the theme used in
+conjunction with this modified version of ``sphinx-multiversion`` is
+`SHIBUYA <https://github.com/lepture/shibuya>`__.
+
+.. attention::
+
+    **Attribution**
+
+    A big thanks to the original author and project
+    `Jan Holthuis <https://github.com/Holzhaus>`_, as well as
+    `Samuel Dowling <https://github.com/samuel-emrys>`_, as we took various patches for
+    the plugin from his fork.
+
+    Note: Both projects are published under the `BSD-2 license <https://opensource.org/license/bsd-2-clause>`_.
+
+    * https://github.com/sphinx-contrib/multiversion
+    * https://github.com/samuel-emrys/sphinx-multiversion
+
+.. note::
+
+    In the long term, it would be advantageous to remove unnecessary features and code
+    that are not required for Exasol's projects. Adding further tests would also be
+    beneficial. However, the primary goal was to create a low-effort, stable
+    multi-version support solution for our projects.

doc/user_guide/features/documentation/multiversion.rst

@@ -0,0 +1,70 @@
+Troubleshooting
+===============
+
+Duplicated label error when building documentation
+--------------------------------------------------
+
+If you have an error similar to this one:
+.. :code-block::
+
+    Warning, treated as error:
+    integration-test-docker-environment/doc/changes/changes_0.10.0.md:5:duplicate
+    label summary, other instance in
+    integration-test-docker-environment/doc/changes/changes_0.1.0.md'
+
+then, this might be caused by sphinx extension ``sphinx.ext.autosectionlabel``.
+Try to remove this extension in ``doc/conf.py``.
+
+
+.. _faq_multiversion_build_warnings:
+
+Warning while building multiversion documentation
+--------------------------------------------------
+When running ``nox -s docs:multiversion``, you receive the following warnings during the build:
+
+.. code-block::
+
+    WARNING: unknown config value 'smv_metadata_path' in override, ignoring
+    WARNING: unknown config value 'smv_current_version' in override, ignoring
+
+It is likely that the multiversion extension is not configured in your Sphinx
+configuration (``doc/conf.py``). Try adding it to your configuration and rerun the build.
+
+.. code-block:: python
+
+    extensions = [
+        ...,
+        ...,
+        "exasol.toolbox.sphinx.multiversion",
+    ]
+
+
+
+Missing version selection box in multiversion documentation
+------------------------------------------------------------
+
+You have run ``nox -s docs:multiversion``, but you still do not see any version
+selection box in the upper right corner before the GitHub symbol.
+
+This is likely due to :ref:`faq_multiversion_build_warnings` or
+:ref:`limited_multiversion_documentation`.
+
+
+.. _limited_multiversion_documentation:
+
+Limited previous versions in multiversion documentation
+-------------------------------------------------------
+
+If not all previous versions of the project are available via the version selection box
+of the multiversion documentation, it is likely due to the fact that the unavailable
+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>`__.

doc/user_guide/features/documentation/troubleshooting.rst

@@ -8,6 +8,7 @@ Features
 
     collecting_metrics
     creating_a_release
+    documentation/index
 
 Uniform Project Layout
 ----------------------