diff --git a/doc/changes/unreleased.md b/doc/changes/unreleased.md index 18c65e34c..e40582771 100644 --- a/doc/changes/unreleased.md +++ b/doc/changes/unreleased.md @@ -1,5 +1,9 @@ # Unreleased +## Documentation + +* #648: Moved sonar setup instructions in the User guide + ## Features * #649: Restricted noxconfig usage throughout exasol.toolbox to only exasol.toolbox.nox.* diff --git a/doc/user_guide/configuration.rst b/doc/user_guide/configuration.rst new file mode 100644 index 000000000..0967c43f0 --- /dev/null +++ b/doc/user_guide/configuration.rst @@ -0,0 +1,13 @@ +.. _ptb_configuration: + +Configuration +============= + +Many components of the PTB can be configured. Adjustment might be required +especially when starting a new project. + +.. toctree:: + :maxdepth: 1 + + features/metrics/sonar + Formatting diff --git a/doc/user_guide/features/formatting_code/configuration.rst b/doc/user_guide/features/formatting_code/configuration.rst new file mode 100644 index 000000000..7a7135265 --- /dev/null +++ b/doc/user_guide/features/formatting_code/configuration.rst @@ -0,0 +1,54 @@ +.. _formatting_configuration: + +Configuring Formatting +++++++++++++++++++++++ + +black +^^^^^ + +Your ``black`` configuration should look similar to this: + +.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml + :language: toml + :start-at: [tool.black] + :end-before: [tool.isort] + +For further configuration options, see +`black configuration `__. + +isort +^^^^^ + +Ensure ``isort`` is configured with compatibility for ``black``: + +.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml + :language: toml + :start-at: [tool.isort] + :end-before: [tool.pylint.master] + +For further configuration options, see +`isort options `__. + + +pyupgrade +^^^^^^^^^ + +No initial configuration of ``pyupgrade`` is required. By default, this is +configured to be derived from the minimum Python version that your project supports +and is defined in the :meth:`exasol.toolbox.config.BaseConfig.pyupgrade_argument`. + +For further configuration options, see the +`pyupgrade documentation `__. + +ruff +^^^^ + +Ensure ``ruff`` is configured like so: + +.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml + :language: toml + :start-at: [tool.ruff.lint] + :end-before: [tool.mypy.overrides] + +For further configuration options, see +`ruff options `__. diff --git a/doc/user_guide/features/formatting_code/index.rst b/doc/user_guide/features/formatting_code/index.rst index a720a43a6..8c2840c83 100644 --- a/doc/user_guide/features/formatting_code/index.rst +++ b/doc/user_guide/features/formatting_code/index.rst @@ -6,6 +6,7 @@ Formatting code .. toctree:: :maxdepth: 2 + configuration troubleshooting The PTB automatically formats code and ensures via a step in the ``checks.yml`` GitHub @@ -51,57 +52,3 @@ deterministic manner. | | | need to be re-formatted | +--------------------+------------------+------------------------------------+ -.. _formatting_configuration: - -Configuration -+++++++++++++ - -black -^^^^^ - -Your ``black`` configuration should look similar to this: - -.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml - :language: toml - :start-at: [tool.black] - :end-before: [tool.isort] - -For further configuration options, see -`black configuration `__. - -isort -^^^^^ - -Ensure ``isort`` is configured with compatibility for ``black``: - -.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml - :language: toml - :start-at: [tool.isort] - :end-before: [tool.pylint.master] - -For further configuration options, see -`isort options `__. - - -pyupgrade -^^^^^^^^^ - -No initial configuration of ``pyupgrade`` is required. By default, this is -configured to be derived from the minimum Python version that your project supports -and is defined in the :meth:`exasol.toolbox.config.BaseConfig.pyupgrade_argument`. - -For further configuration options, see the -`pyupgrade documentation `__. - -ruff -^^^^ - -Ensure ``ruff`` is configured like so: - -.. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/pyproject.toml - :language: toml - :start-at: [tool.ruff.lint] - :end-before: [tool.mypy.overrides] - -For further configuration options, see -`ruff options `__. diff --git a/doc/user_guide/features/index.rst b/doc/user_guide/features/index.rst index 97be87e1d..6a57544fd 100644 --- a/doc/user_guide/features/index.rst +++ b/doc/user_guide/features/index.rst @@ -4,14 +4,14 @@ Features ======== .. toctree:: - :maxdepth: 2 - - metrics/collecting_metrics - creating_a_release - documentation/index - git_hooks/index - formatting_code/index - managing_dependencies + :maxdepth: 2 + + metrics/collecting_metrics + creating_a_release + documentation/index + git_hooks/index + formatting_code/index + managing_dependencies Uniform Project Layout ---------------------- diff --git a/doc/user_guide/features/metrics/collecting_metrics.rst b/doc/user_guide/features/metrics/collecting_metrics.rst index e69f51374..521595851 100644 --- a/doc/user_guide/features/metrics/collecting_metrics.rst +++ b/doc/user_guide/features/metrics/collecting_metrics.rst @@ -1,19 +1,20 @@ -Collecting metrics +Collecting Metrics ================== +The PTB allows you to collect various metrics on the quality of your project +regarding Coverage, Security, and Static Code Analysis. + .. toctree:: - :maxdepth: 2 + :maxdepth: 2 + :hidden: - project_report - sonar + project_report + sonar .. _generated_metrics: -Generated metrics -+++++++++++++++++ - -The PTB allows you to collect various metrics on the quality of your project -regarding Coverage, Security, and Static Code Analysis. +Generating Metrics +++++++++++++++++++ For each metric, there is a dedicated nox session, generating one or multiple files and based on a selected external Python tool. @@ -39,13 +40,13 @@ The GitHub workflows of your project can: * Define multiple test sessions, e.g. for distinguishing fast vs. slow or expensive tests. -Reporting metrics +Reporting Metrics +++++++++++++++++ Currently, the PTB offers two methods to aggregate the :ref:`generated_metrics` into a report: -#. the nox session ``project:report`` +#. Nox session ``project:report`` This is an Exasol-specific summarization tool. For more information, see :ref:`project_report`. #. SonarQube analysis @@ -53,10 +54,11 @@ into a report: `Sonar `__. For further details, see :ref:`sonarqube_analysis` -Both of these reporting options require that the generated files from the :ref:`generated_metrics` -are existing and in the expected formats. As there are metrics for different Python -versions, the PTB uses only the metrics associated with the Python version named first -in the attribute ``python_versions`` of class ``Config`` to the reporting metrics tools. +Both of these reporting options require that the generated files from the +generated metrics are existing and in the expected formats. As there are +metrics for different Python versions, the PTB uses only the metrics +associated with the Python version named first in the attribute +``python_versions`` of class ``Config`` to the reporting metrics tools. To perform this validation, there are two nox sessions. Due to the direct dependence on the nox session ``project:report`` and SonarQube Analysis on the diff --git a/doc/user_guide/features/metrics/project_report.rst b/doc/user_guide/features/metrics/project_report.rst index 92f3aa036..78cbd248f 100644 --- a/doc/user_guide/features/metrics/project_report.rst +++ b/doc/user_guide/features/metrics/project_report.rst @@ -1,7 +1,8 @@ .. _project_report: -``project:report`` -================== +Nox session ``project:report`` +============================== + After collecting the metrics described in by :ref:`generated_metrics`, you can use the nox session ``project:report`` to create a report using one of the following formats: diff --git a/doc/user_guide/features/metrics/sonar.rst b/doc/user_guide/features/metrics/sonar.rst index 2db9c69ed..91db1cfe5 100644 --- a/doc/user_guide/features/metrics/sonar.rst +++ b/doc/user_guide/features/metrics/sonar.rst @@ -1,6 +1,6 @@ .. _sonarqube_analysis: -SonarQube analysis +SonarQube Analysis ================== The PTB supports using `SonarQube Cloud `__ @@ -12,9 +12,9 @@ SonarQube analysis fails. The PTB includes instructions to set up a GitHub bot to display the results of the Sonar analysis in your pull requests as a stylized comment and workflow result. -Section :ref:`configuration` gives instructions for public and private repositories. +Section :ref:`sonar_configuration` gives instructions for public and private repositories. -.. _configuration: +.. _sonar_configuration: Configuration +++++++++++++ diff --git a/doc/user_guide/user_guide.rst b/doc/user_guide/user_guide.rst index ad7576938..1e2957b3e 100644 --- a/doc/user_guide/user_guide.rst +++ b/doc/user_guide/user_guide.rst @@ -8,6 +8,7 @@ dependencies getting_started + configuration features/index workflows customization