Improve general module documentation

Split `nox` sections into a section for writing the `noxfile.py` and a
section about configuring the `pyproject.toml` file.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

src/frequenz/repo/config/__init__.py

@@ -14,24 +14,11 @@
 
 ## `nox`
 
+### Writing the `noxfile.py`
+
 Projects wanting to use `nox` to run lint checkers and other utilities can use
 the [`frequenz.repo.config.nox`][] package.
 
-Make sure to add this package as `dev` dependency to your project's
-`pyproject.tom` file, for example:
-
-```toml
-[project.optional-dependencies]
-nox = [
-    "nox == 2022.11.21",
-    "frequenz-repo-config[lib] == 0.1.0",
-]
-```
-
-Please note the `lib` optional dependency. Make sure you specify the correct
-one based on the type of your project (`api`, `actor`, `app`, `lib`). Also make
-sure to adjust the versions.
-
 When writing the `noxfile.py` you should import the `nox` module from this
 package and use the [`frequenz.repo.config.nox.configure`][] function,
 which will configure all nox sessions.
@@ -40,9 +27,9 @@
 in the [`frequenz.repo.config.nox.default`][] module. For example:
 
 ```python
-from frequenz.repo import config
+from frequenz.repo.config import nox
 
-config.nox.configure(config.nox.default.lib_config)
+nox.configure(nox.default.lib_config)
 ```
 
 Again, make sure to pick the correct default configuration based on the type of
@@ -53,11 +40,11 @@
 [`copy()`][frequenz.repo.config.nox.config.Config.copy] method:
 
 ```python
-from frequenz.repo import config
+from frequenz.repo.config import nox
 
-conf = config.nox.default.lib_config.copy()
-conf.opts.black.append("--diff")
-config.nox.configure(conf)
+config = nox.default.lib_config.copy()
+config.opts.black.append("--diff")
+nox.configure(config)
 ```
 
 If you need further customization or to define new sessions, you can use the
@@ -73,6 +60,93 @@
 
 - [`frequenz.repo.config.nox.util`][]: General purpose utility functions.
 
+### `pyproject.toml` configuration
+
+All sessions configured by this package expect the `pyproject.toml` file to
+define specific *dev* dependencies that will be used by the different `nox`
+sessions.
+
+The following optional dependencies are used and must be defined:
+
+- `dev-docstrings`: Dependencies to lint the documentation.
+
+  At least these packages should be included:
+
+  - `pydocstyle`: To check the docstrings' format.
+  - `darglint`: To check the docstrings' content.
+
+- `dev-formatting`: Dependencies to check the code's formatting.
+
+  At least these packages should be included:
+
+  - `black`: To check the code's formatting.
+  - `isort`: To check the imports' formatting.
+
+- `dev-mypy`: Dependencies to run `mypy` to check the code's type annotations.
+
+  At least these packages should be included:
+
+  - `mypy`: To check the code's type annotations.
+
+- `dev-pylint`: Dependencies to run `pylint` to lint the code.
+
+  At least these packages should be included:
+
+  - `pylint`: To lint the code.
+
+- `dev-pytest`: Dependencies to run the tests using `pytest`.
+
+  At least these packages should be included:
+
+  - `pytest`: To run the tests.
+
+For some of these you should install too any other dependencies that are used
+by the project. For example, if the project uses `pytest-asyncio`, you should
+include it in the `dev-pytest` optional dependency.
+
+It is also recommended, but not required, to provide a global `dev` optional
+dependency that includes all the other optional dependencies, so users can
+install all the dependencies needed while developing the project without having
+to run `nox`, which might be a bit slow if you want to do quick iterations.
+
+```console
+$ pip install -e .[dev]
+...
+$ pytest
+...
+```
+
+Here is a sample `pyproject.toml` file that defines all the optional
+dependencies:
+
+```toml
+[project]
+name = "my-package"
+# ...
+
+[project.optional-dependencies]
+dev-docstrings = ["pydocstyle == 6.3.0", "darglint == 1.8.1"]
+dev-formatting = ["black == 23.3.0", "isort == 5.12.0"]
+dev-mypy = [
+  "mypy == 1.1.1",
+  # For checking tests
+  "my-package[dev-pytest]",
+]
+dev-pylint = [
+  "pylint == 2.17.1",
+  "pylint-google-style-guide-imports-enforcing == 1.3.0",
+  # For checking tests
+  "my-package[dev-pytest]",
+]
+dev-pytest = [
+  "pytest == 7.2.2",
+  "pytest-asyncio == 0.21.0",
+  "pytest-mock == 3.10.0",
+]
+dev = [
+  "my-package[dev-docstrings,dev-formatting,dev-mypy,dev-nox,dev-pylint,dev-pytest]",
+]
+```
 
 # APIs