Update documentation regarding nox tasks and PYTHONPATH (#199)

Author: Nicoretti

doc/changes/unreleased.md

@@ -8,3 +8,6 @@
 
 * #162: Updated templates for GitHub workflows to inherit secrets by default
 * #52: Add support for caching python dependencies in GitHub workflows
+
+## 📚 Documentation
+* Updated information about nox tasks and `PYTHONPATH` setup

doc/faq.rst

@@ -0,0 +1,18 @@
+.. _faq_toolbox:
+
+:octicon:`question` FAQ
+=======================
+
+
+.. _faq_no_module_noxconfig:
+
+No Module Named 'noxconfig'
+---------------------------
+
+The error, :code:`ModuleNotFoundError: No module named 'noxconfig'`, often appears on systems such as Fedora, where the current path may not be included in the :code:`PYTHONPATH`. This issue is elaborated upon at https://fedoraproject.org/wiki/Changes/PythonSafePath. Accordingly, it may be necessary to correctly set the :code:`PYTHONPATH` before initiating nox, as our nox tasks anticipate the `noxconfig` module to be located within the python path.
+
+There are several methods to configure your shell:
+
+    1. For a one-time setup: :code:`PYTHONPATH=\`pwd\` nox -s task`
+    2. For a general setup: :code:`export PYTHONPATH=`pwd``
+    3. Alternatively, tools like `direnv <https://direnv.net>`_ can be used.

doc/index.rst

@@ -43,6 +43,12 @@ Documentation of the Exasol-Toolbox
 
         Document outlining the architectural and design principles and decisions in this project.
 
+    .. grid-item-card:: :octicon:`question` FAQ
+        :link: faq_toolbox
+        :link-type: ref
+
+        Frequently asked questsions.
+
 
 .. toctree::
    :maxdepth: 1
@@ -53,6 +59,7 @@ Documentation of the Exasol-Toolbox
    tools
    github_actions/github_actions
    api
+   faq
    changes/changelog
 
 

doc/user_guide/getting_started.rst

@@ -69,6 +69,16 @@ forward and you just can use the example *noxfile.py* bellow.
 
 .. literalinclude:: ../../noxfile.py
    :language: python3
+   :end-before: # entry point for debugging
+
+
+.. attention::
+
+    Keep in mind that the current path may not be included in the :code:`PYTHONPATH`, depending on the operating system you are using. This is explained in more detail in this resource: https://fedoraproject.org/wiki/Changes/PythonSafePath. Thus, it might be necessary to properly set the :code:`PYTHONPATH` before running nox. This is because our nox tasks expect the `noxconfig` module to be located within the python path.
+
+    For additional information on resolving this issue, please :ref:`refer to <faq_no_module_noxconfig>`.
+
+        
 
 6. Setup the pre-commit hooks
 +++++++++++++++++++++++++++++

noxfile.py

@@ -7,7 +7,7 @@
 # default actions to be run if nothing is explicitly specified with the -s option
 nox.options.sessions = ["fix"]
 
-
+# entry point for debugging
 def main() -> None:
     """
     This excerpt was taken from nox.__main__.py. Generally, users should invoke Nox using the CLI provided by the Nox package.