Switch references in getting_started to cookiecutter-template

Author: ArBridgeman

doc/user_guide/features/formatting_code/index.rst

@@ -38,24 +38,29 @@ deterministic manner.
 `pre-commit`
 ++++++++++++
 
+.. _formatting_configuration:
 
 Configuration
 +++++++++++++
+black
+^^^^^
 
+Your ``black`` configuration should look similar to this:
 
-Ensure ``isort`` is configured with compatibility for ``black``:
-
-.. code-block:: toml
+.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml
+  :language: toml
+  :start-at: [tool.black]
+  :end-before: [tool.isort]
 
-    [tool.isort]
-    profile = "black"
-    force_grid_wrap = 2
-
-Additionally, your black configuration should look similar to this:
+isort
+^^^^^
+Ensure ``isort`` is configured with compatibility for ``black``:
 
-.. code-block:: toml
+.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml
+  :language: toml
+  :start-at: [tool.isort]
+  :end-before: [tool.pylint.master]
 
-    [tool.black]
-    line-length = 88
-    verbose = false
-    include = "\\.pyi?$"
+pyupgrade
+^^^^^^^^^
+No initial configuration of ``pyupgrade`` is required.

doc/user_guide/features/formatting_code/troubleshooting.rst

@@ -11,8 +11,8 @@ If when you execute:
 #. Run ``project:format``
 
 you receive an error from ``project:format`` (i.e. ``isort`` or ``black``), it it
-likely that you need to update your configuration to align with :ref:formatting_code.
-# TODO REFERENCE
+likely that you need to update your configuration to align with
+:ref:`formatting_configuration`.
 
 The automatic formatting is doing x, but we shouldn't do that because of y
 ---------------------------------------------------------------------------
@@ -42,20 +42,20 @@ might want to ignore automatically applied formatting.
 In the ``checks.yml``, ``project:format`` wants me to reformat code I did not modify
 ------------------------------------------------------------------------------------
 
-This is likely due to one of our tools (i.e. `black`) being upgraded. Within the
-`pyproject.toml` of the PTB, dependencies are specified to allow
-compatible versions or a restricted version range (i.e., `^6.0.1`, `>=24.1.0,<26.0.0`).
+This is likely due to one of our tools (i.e. ``black``) being upgraded. Within the
+``pyproject.toml`` of the PTB, dependencies are specified to allow
+compatible versions or a restricted version range (i.e., ``^6.0.1``, ``>=24.1.0,<26.0.0``).
 Such specifications should restrict major reformatting changes to coincide only with a
 new major version of the PTB. However, sometimes a tool's versioning may not properly
 adhere to semantic versioning.
 
 If you encounter this scenario, please:
 
-#. Ensure that your `pyproject.toml` has the PTB restricted to compatible versions
-   (i.e., `^1.7.0`).
+#. Ensure that your ``pyproject.toml`` has the PTB restricted to compatible versions
+   (i.e., ``^1.7.0``).
 #. Identify which tool is trying to reformat files that you did not modify.
-#. Reset your `poetry.lock` to align with what's in the project's **default branch**.
-#. More selectively update your `poetry.lock` with `poetry update <package-name>`.
+#. Reset your ``poetry.lock`` to align with what's in the project's **default branch**.
+#. More selectively update your ``poetry.lock`` with `poetry update <package-name>`.
 #. Share with your team which tool & version led to the unexpected changes. So that
    other PTB users do not experience the same difficulties, we will update the PTB with
    a patch version to avoid this tool's version and later do a major release to better

doc/user_guide/getting_started.rst

@@ -91,54 +91,38 @@ Integrating Exasol-Toolbox into your Project
 2. Provide a project configuration
 ++++++++++++++++++++++++++++++++++
 Make sure you provide the required configuration. Configuration for the exasol-toolbox gets provided by creating
-a ``noxconfig.py`` file in the workspace root. This file should contain at least
-a single module constant with the name **PROJECT_CONFIG** pointing to an object,
-which is required to to provide the following attributes:
-
-* .. py:attribute:: root
-    :type: Path
-
-* .. py:attribute:: doc
-    :type: Path
-
-* .. py:attribute:: version_file
-    :type: Path
-
-Alternatively you can use the *noxconfig.py* file bellow and adjust the value of the attributes if needed:
+a ``noxconfig.py`` file in the workspace root. This file should be similar to the
+example shown below.
 
 .. note::
 
-   Be aware that the plugin definitions are completely optional. For further details on plugins, see the customization section.
+   For further details on plugins, see the customization section.
 
-.. literalinclude:: ../../noxconfig.py
+.. literalinclude:: ../../project-template/{{cookiecutter.repo_name}}/noxconfig.py
    :language: python3
 
 3. Configure the tooling
 ++++++++++++++++++++++++
-In order to make all standard task work properly, you need add the configuration settings below to your ``pyproject.toml``,
-and adjust the following settings to your project needs:
+Configuration values for the tooling should be defined in the ``pyproject.toml``.
+Copy the example below & adapt it for your project's specific needs.
 
-* coverage
-    - source
-    - fail_under
-* pylint
-    - fail-under
-* mypy (overrides)
-    - module
+.. literalinclude:: ../../project-template/{{cookiecutter.repo_name}}/pyproject.toml
+  :language: toml
+  :start-after: # Tooling
+
+For further reference, see the specific configurations for:
+
+* :ref:`formatting code <formatting_configuration>`
 
-.. literalinclude:: ../../pyproject.toml
-    :language: toml
-    :start-after: # Tooling
 
 4. Make the toolbox tasks available
 +++++++++++++++++++++++++++++++++++
-In order to use the standard toolbox task via nox, just import them in your ``noxfile.py``.
-If you only need the standard tasks provided by the toolbox, your ``noxfile.py`` is straight
-forward, and you just can use the example ``noxfile.py`` below.
+To use the standard toolbox task via nox, just import them in your ``noxfile.py``.
+If you only need the standard tasks provided by the toolbox, your ``noxfile.py`` is
+straightforward, and you just can use the example ``noxfile.py`` below.
 
-.. literalinclude:: ../../noxfile.py
+.. literalinclude:: ../../project-template/{{cookiecutter.repo_name}}/noxfile.py
    :language: python3
-   :end-before: # entry point for debugging
 
 
 .. attention::
@@ -147,16 +131,14 @@ forward, and you just can use the example ``noxfile.py`` below.
 
     For additional information on resolving this issue, please :ref:`refer to <faq_no_module_noxconfig>`.
 
-
-
 5. Set up the pre-commit hooks [optional]
 +++++++++++++++++++++++++++++++++++++++++
 
 #. Add a :code:`.pre-commit-config.yaml` file to your project root
 
     If you want to reuse Nox tasks in the pre-commit hooks, feel free to get some inspiration from the Python toolbox itself:
 
-    .. literalinclude:: ../../.pre-commit-config.yaml
+    .. literalinclude:: ../../project-template/{{cookiecutter.repo_name}}/.pre-commit-config.yaml
        :language: yaml
 
 #. Enable pre-commit hooks for your workspace

project-template/{{cookiecutter.repo_name}}/pyproject.toml

@@ -30,6 +30,7 @@ exasol-toolbox = "^1.6.0"
 requires = ["poetry-core>=2.0.0"]
 build-backend = "poetry.core.masonry.api"
 
+# Tooling - marking what to show in the documentation
 [tool.coverage.run]
 relative_files = true
 source = [

pyproject.toml

@@ -74,7 +74,6 @@ cookiecutter = "^2.6.0"
 requires = ["poetry-core>=2.0.0"]
 build-backend = "poetry.core.masonry.api"
 
-# Tooling
 [tool.coverage.run]
 relative_files = true
 source = [