add docs about the support for Hatch Libraries, by using the hatch-polylith-bricks build hook plugin

Author: DavidVujic

docs/deployment.md

@@ -42,16 +42,13 @@ pip install the-built-artifact.whl
 
 ### Packaging a Library
 
-__NOTE:__ only supported for Poetry.
+The _Python tools for the Polylith Architecture_ has support for building libraries to be published at PyPI,
+even if it isn't the main use case.
 
-_Hatch support for packaging libraries is currently being developed._
-
-The plugin has support for building libraries to be published at PyPI, even if it isn't the main use case.
-But why? By default, the code in one library will share the same top namespace with other libraries that are
-built from the same Polylith Monorepo. 
-
-To solve this, there's a feature available that will organize code according to a custom top namespace and re-write the imports.
+Important note: by default, the code in one library will share the same top namespace with other libraries that are
+built from the same Polylith Monorepo. To solve this, there's a feature available that will organize code according to a custom top namespace and re-write the imports.
 
+#### Poetry
 You can choose a custom namespace to be used in the build process, by using the `--with-top-namespace` flag.
 This is available for __Python 3.9__ and above.
 
@@ -61,7 +58,26 @@ The `build-project` command, with a custom top namespace:
 poetry build-project --with-top-namespace my_custom_namespace
 ```
 
-By using the `--with-top-namespace` flag, the built artifact will look something like this:
+#### Hatch
+There is a Build Hook plugin for Polylith - `hatch-polylith-bricks` -  that is added like this:
+``` toml
+[build-system]
+requires = ["hatchling", "hatch-polylith-bricks"]
+build-backend = "hatchling.build"
+```
+
+As described in the [Projects & pyproject.toml](projects.md) section,
+the project-specific bricks are added in the `[tool.polylith.bricks]` section for libraries.
+
+A custom top namespace is defined in the hook configuration of `pyproject.toml`:
+
+``` toml
+[tool.hatch.build.hooks.polylith-bricks]
+top-namespace = "my_custom_namespace"
+```
+
+#### Result
+By using the Poetry build-project flag or the Hatch Build Hook, the built artifact will look something like this:
 ```shell
 my_custom_namespace/
     /my_package

docs/projects.md

@@ -57,3 +57,26 @@ Bricks are added in the _tool.hatch.build.force-include_ section:
 
 The `bases` and `components` folders are located at the workspace root.
 The project-specific `pyproject.toml` file is located in a subfolder of the `projects` folder.
+
+
+### Library setup for Hatch: the project-specific pyproject.toml file(s)
+There is a special setup to avoid namespace collision,
+when more than one library is packaged and published from the same Polylith Workspace.
+
+This includes a Hatch Build Hook plugin that is made for Polylith: `hatch-polylith-bricks`
+
+``` toml
+[build-system]
+requires = ["hatchling", "hatch-polylith-bricks"]
+build-backend = "hatchling.build"
+```
+
+Add bricks to a project by using `tool.polylith.bricks`;
+``` toml
+[tool.polylith.bricks]
+"../../bases/my_namespace/my_base" = "my_namespace/my_base"
+"../../components/my_namespace/my_component" = "my_namespace/my_component"
+"../../components/my_namespace/my_other_component" = "my_namespace/my_other_component"
+```
+
+NOTE: this setup works for other artifacts too, but also needs the `hatch-polylith-bricks` plugin.