Update the documentation

Author: johnslavik

docs/guide/contributors/architecture.md

@@ -98,19 +98,30 @@ The tools used in tasks have their configuration files stored in the `config` fo
 
 ## Sources
 
-Sources are located in the `src` folder, following the [src-layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/). We use [PDM-Backend](https://backend.pdm-project.org/) to build source and wheel distributions, and configure it in `pyproject.toml` to search for packages in the `src` folder.
+Sources are located in the `packages/` subfolders, following the [src-layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/).
+We use [Hatch](https://hatch.pypa.io/latest/) to build source and wheel distributions, and configure it in `pyproject.toml`.
 
 ## Tests
 
-Our test suite is located in the `tests` folder. It is located outside of the sources as to not pollute distributions (it would be very wrong to publish a `tests` package as part of our distributions, since this name is extremely common), or worse, the public API. The `tests` folder is however included in our source distributions (`.tar.gz`), alongside most of our metadata and configuration files. Check out `pyproject.toml` to get the full list of files included in our source distributions.
+Our test suite is located in the `tests` folder. It is located outside of the sources as to not pollute distributions (it would be very wrong to publish a `tests` package as part of our distributions, since this name is extremely common), or worse, the public API. The `tests` folder is however included in our source distributions (`.tar.gz`), alongside most of our metadata and configuration files. Check out our `pyproject.toml` files to get the full list of files included in our source distributions for every individual package within the `packages/` folder.
 
 The test suite is based on [pytest](https://docs.pytest.org/en/8.2.x/). Test modules reflect our internal API structure, and except for a few test modules that test specific aspects of our API, each test module tests the logic from the corresponding module in the internal API. For example, `test_finder.py` tests code of the `griffe._internal.finder` internal module, while `test_functions` tests our ability to extract correct information from function signatures, statically. The general rule of thumb when writing new tests is to mirror the internal API. If a test touches to many aspects of the loading process, it can be added to the `test_loader` test module.
 
 ## Program structure
 
-The internal API is contained within the `packages/griffelib/src/griffe/_internal` folder. The top-level `griffe/__init__.py` module exposes all the public API, by importing the internal objects from various submodules of `griffe._internal`.
+Griffe is split into two pieces: the library and the CLI.
 
-Users then import `griffe` directly, or import objects from it.
+Each of them has an internal API contained within an `_internal` folder:
+- `packages/griffelib/src/griffe/_internal` for the library,
+- `packages/griffecli/src/griffecli/_internal` for the CLI.
+
+Griffe can be installed in library-only mode, which means that the CLI package from `packages/griffecli` is not present.
+Library-only mode can be preferred if the user does not utilize the CLI functionality of Griffe and does not want to incorporate its dependencies.
+
+The top-level `packages/griffelib/src/griffe/__init__.py` module exposes all the public API available: it always re-exports internal objects from various submodules of `griffe._internal` and, if the CLI is installed, it re-exports the public API of `griffecli` as well.
+
+Users then import `griffe` directly, or import objects from it. If they don't have `griffecli` installed, they cannot import the CLI-related functionality,
+such as [`griffecli.check`][].
 
 We'll be honest: our code organization is not the most elegant, but it works :shrug: Have a look at the following module dependency graph, which will basically tell you nothing except that we have a lot of inter-module dependencies. Arrows read as "imports from". The code base is generally pleasant to work with though.
 

docs/installation.md

@@ -118,6 +118,8 @@ If you only need the library for API introspection and analysis without the CLI
 
      </div>
 
+This installs the `griffe` package as usual, but without the CLI program, nor its API, nor its dependencies.
+
 ## Install as a tool only
 
 === ":simple-python: pip"
@@ -177,6 +179,3 @@ Or as a Python module:
 ```console
 $ python -m griffe check mypackage
 ```
-
-TIP: **Alternative CLI Package**
-If you need to run Griffe without the full library, you can also use `python -m griffecli` instead of `python -m griffe`. This runs the CLI directly from the `griffecli` package.