docs: add keyring troubleshooting (#1289)

* docs: add keyring troubleshooting * Update docs/source/commands.rst Co-authored-by: Anna Stuchlik <[email protected]> --------- Co-authored-by: Anna Stuchlik <[email protected]>
scylladb · Nov 22, 2024 · ae70bc5 · ae70bc5
1 parent 4ead875
commit ae70bc5
Show file tree

Hide file tree

Showing 3 changed files with 43 additions and 4 deletions.
diff --git a/docs/source/commands.rst b/docs/source/commands.rst
@@ -76,14 +76,37 @@ To decrease verbosity, use the option ``-Q``:
 
         make preview SPHINXOPTS=-Q
 
-To fix the error ``pyproject.toml changed significantly since poetry.lock was last generated.``, run the following command:
+
+Troubleshooting
+...............
+
+Issue: pyproject.toml changed significantly since poetry.lock was last generated
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+**Solution:**
+
+#. Run the following command:
 
     .. code:: console
 
         poetry lock --no-update
 
-    Then, run the preview command again.
+#. Run the `make preview` command again.
+
+Issue: Keyring asks for a password
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This issue is due to a known problem with Poetry that primarily affects GNOME users. For more details, see `poetry/poetry#8761 <https://github.com/python-poetry/poetry/issues/8761>`_.
+
+**Solution:**
+
+#. Edit `docs/Makefile` to add the `POETRY` variable as follows:
+
+    .. code::
+
+        POETRY = PYTHON_KEYRING_BACKEND=keyring.backends.null.Keyring poetry
 
+#. Run the `make preview` command again.
 
 multiversionpreview
 ===================

diff --git a/docs/source/getting-started/installation.rst b/docs/source/getting-started/installation.rst
@@ -52,7 +52,16 @@ Step 3: Preview the site locally
 
 #. Delete or adapt the sample documentation files under ``docs/source``.
 
-#. From the command line, run ``make preview`` within the ``docs`` folder. Fix any warnings raised by Sphinx.
+#. From the command line, run ``make preview`` within the ``docs`` folder:
+
+    .. code-block:: console
+
+        cd docs
+        make preview
+
+    .. tip:: For troubleshooting, refer to the :ref:`preview command <Make_Preview>` documentation.
+
+#. Fix any warnings raised by Sphinx.
 
 #. Once the docs build without errors, open ``http://127.0.0.1:5500/`` to preview the generated site.
 

diff --git a/docs/source/getting-started/quickstart.rst b/docs/source/getting-started/quickstart.rst
@@ -63,7 +63,14 @@ This file contains scripts that you can run to create a testing environment, com
 
 To preview the docs locally:
 
-#. From the command line, run ``make preview`` within the ``docs`` folder.
+#. From the command line, run ``make preview`` within the ``docs`` folder:
+
+    .. code-block:: console
+
+        cd docs
+        make preview
+
+    .. tip:: For troubleshooting, refer to the :ref:`preview command <Make_Preview>` documentation.
 
 #. Open ``http://127.0.0.1:5500/`` to preview the generated site with you changes.