Merge ~jugmac00/lpci:improve-contribution-documentation into lpci:main

[Jürgen Gmach]

Improve the contribution documentation

[Jürgen Gmach (jugmac00)]

@Guruprasad: I added a couple of comments why I think the documentation needed some updates. What do you think?

[Guruprasad (lgp171188)]

Should running the plain `tox` command run the unit tests twice - once each for the unit test environment and once for the coverage environment. The latter is sufficient to cover both needs, right?

[Jürgen Gmach (jugmac00)]

> Should running the plain `tox` command run the unit tests twice - once each for the unit test environment and once for the coverage environment.

Yes, this is a common approach.

Once we use tox 4, we can use a different approach. As then it is more easily possible to declare dependencies between environments, resp. run environments in succession.

Other approaches I have seen.... Every testenv, which runs tests, also runs coverage. This approach works nicely for CI, but is pretty annoying when developing locally, as then you always need to scroll up to find the reason for error.

So all in all - I think we are using the best approach.

[Guruprasad (lgp171188)]

LGTM 👍

review: Approve

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index e4c23d1..64753c6 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -6,8 +6,6 @@ Prerequisites
 
 * Python 3.8+
 * `tox <https://tox.wiki/en/latest/>`_
-* `pyenv <https://github.com/pyenv/pyenv>`_, if you want to use and test against
-  multiple versions of Python
 
 Usage
 -----
@@ -23,20 +21,23 @@ List the ``tox`` environments available for this project.
 
   .. code:: bash
 
-    $ tox -l
-    lint
-    mypy
-    py38
-    py39
-    py310
+    $ tox -lv
+    default environments:
+    lint     -> run linters
+    mypy     -> run static type checker
+    py38     -> run test suite
+    py39     -> run test suite
+    py310    -> run test suite
+    coverage -> generate coverage report
 
 Run the project's tests.
 
   .. code:: bash
 
-    $ tox -e py38  #  Replace with the installed Python version, if 3.8 is unavailable.
+    $ tox -e py38  #  You can replace ``py38`` with another Python version.
 
-Since ``tox`` uses ``pytest`` under the hood to run the tests, arguments can be passed to pytest.
+Since ``tox`` uses `pytest <https://docs.pytest.org/>`_ under the hood to run
+the tests, arguments can be passed to ``pytest``.
 
   .. code:: bash
 
@@ -50,14 +51,15 @@ Run the tests with coverage.
 
     $ tox -e coverage
 
-Run the linter.
+Run the linters.
 
   .. code:: bash
 
     $ tox -e lint
 
-Alternatively, you can run ``pre-commit install`` to install the git pre-commit hooks,
-which run the linter.
+We also support running linters via `pre-commit <https://pre-commit.com/>`_.
+If you want ``pre-commit`` to run automatically on ``git commit``,
+you need to run ``pre-commit install`` once.
 
 Run the ``mypy`` static type checker.
 
@@ -72,12 +74,18 @@ Update the requirements and regenerate ``requirements.txt``.
     $ <modify requirements.in>
     $ tox -e pip-compile
 
-If any of the ``tox`` environments use a version of Python that is not installed, edit
-``tox.ini`` and replace the value for the ``basepython`` key under that environment.
+Build the documentation locally.
 
-To update the `project's documentation
-<https://lpcraft.readthedocs.io/en/latest/>`_, you need to trigger a manual
-build on the project's dashboard on https://readthedocs.org.
+  .. code:: bash
+
+    $ tox -e docs
+
+.. note::
+
+    In order to update the `project's documentation
+    <https://lpcraft.readthedocs.io/en/latest/>`_ online,
+    after having pushed your changes to the repository, you need to trigger a
+    manual build on the project's dashboard on https://readthedocs.org.
 
 Getting help
 ------------
diff --git a/tox.ini b/tox.ini
index 318e847..cba2529 100644
--- a/tox.ini
+++ b/tox.ini
@@ -10,6 +10,8 @@ skip_missing_interpreters =
     true
 
 [testenv]
+description =
+    run test suite
 commands =
     pytest {posargs}
 deps =
@@ -17,6 +19,8 @@ deps =
     .[test]
 
 [testenv:lint]
+description =
+    run linters
 basepython =
     python3.8
 deps =
@@ -26,6 +30,8 @@ commands =
     pre-commit run -a
 
 [testenv:pip-compile]
+description =
+    update and regenerate requirements.txt
 basepython =
     python3.8
 deps =
@@ -35,6 +41,8 @@ commands =
     pip-compile
 
 [testenv:mypy]
+description =
+    run static type checker
 basepython =
     python3.8
 deps =
@@ -46,6 +54,8 @@ commands =
     mypy --cache-dir="{envdir}/mypy_cache" --strict {posargs:lpcraft}
 
 [testenv:coverage]
+description =
+    generate coverage report
 deps =
     -r requirements.txt
     .[test]
@@ -56,6 +66,9 @@ commands =
     coverage report -m  --fail-under=100
 
 [testenv:docs]
+description =
+    generate documentation
+# the Python version here matches the one in .readthedocs.yaml
 basepython = python3.9
 extras = docs
 commands =