Merge pull request #3 from DavidVujic/hatch-docs

docs: add Hatch-specific documentation

Author: DavidVujic

docs/commands.md

@@ -5,10 +5,16 @@
 ## Create a workspace
 This will create a Polylith workspace, with a basic Polylith folder structure.
 
+### Poetry
 ``` shell
 poetry poly create workspace --name my_example_namespace --theme loose
 ```
 
+### Hatch
+``` shell
+hatch run poly create workspace --name my_example_namespace --theme loose
+```
+
 ### Options
 `--name` (required) the workspace name, that will be used as the single top namespace for all bricks. __Choose the name wisely.__
 Have a look in [PEP-423](https://peps.python.org/pep-0423/#respect-ownership) for naming guidelines.
@@ -32,10 +38,16 @@ These are added for any initial commits of the folder structure, and can safely
 ## Create a component
 This command will create a component - i.e. a Python package in a namespaced folder.
 
+### Poetry
 ``` shell
 poetry poly create component --name my_example_component
 ```
 
+### Hatch
+``` shell
+hatch run poly create component --name my_example_component
+```
+
 ### Options
 `--name` (required) the name of the component.
 
@@ -45,10 +57,16 @@ It will also be added in the README, when enabled in the configuration. See [con
 ## Create a base
 This command will create a base - i.e. a Python package in a namespaced folder.
 
+### Poetry
 ``` shell
 poetry poly create base --name my_example_base
 ```
 
+### Hatch
+``` shell
+hatch run poly create base --name my_example_base
+```
+
 ### Options
 `--name` (required) the name of the base.
 
@@ -58,10 +76,16 @@ It will also be added in the README, when enabled in the configuration. See [con
 ## Create a project
 This command will create a project - i.e. a pyproject.toml in a project folder.
 
+### Poetry
 ``` shell
 poetry poly create project --name my_example_project
 ```
 
+### Hatch
+``` shell
+hatch run poly create project --name my_example_project
+```
+
 ### Options
 `--name` (required) the name of the project.
 
@@ -71,20 +95,32 @@ poetry poly create project --name my_example_project
 ## Info
 Show info about the workspace:
 
+### Poetry
 ``` shell
 poetry poly info
 ```
 
+### Hatch
+``` shell
+hatch run poly info
+```
+
 ### Options
 `--short` Display a view that is better adjusted to Workspaces with many projects.
 
 ## Diff
 Shows what has changed since the most recent stable point in time:
 
+### Poetry
 ``` shell
 poetry poly diff
 ```
 
+### Hatch
+``` shell
+hatch run poly diff
+```
+
 The `diff` command will compare the current state of the repository, compared to a `git tag`.
 The tool will look for the latest tag according to a certain pattern, such as `stable-*`.
 The pattern can be configured in `workspace.toml`.
@@ -94,22 +130,53 @@ It is also useful when running tests for changed bricks only.
 
 
 ### Testing
-Example, how to run __pytest__ for changed bricks only:
+Example, how to run __pytest__ for changed bricks only.
+
+### Poetry
 ``` shell
 # store the comma-separated list of bricks in a bash variable
 changes="$(poetry poly diff --bricks --short)"
 
 # transform it into a pytest query,
 # i.e. from "hello,world,something" to "hello or world or something"
 query="${changes//,/ or }"
+```
+
+Run the test, filtered by keyword expression
 
-# run the test, filtered by keyword expression
+``` shell
 poetry run pytest -k <<< echo "$query"
+```
+
+or run the test, filtered by pytest markers
 
-# or run the test, filtered by pytest markers
+``` shell
 poetry run pytest -m <<< echo "$query"
 ```
 
+### Hatch
+``` shell
+# store the comma-separated list of bricks in a bash variable
+changes="$(hatch run poly diff --bricks --short)"
+
+# transform it into a pytest query,
+# i.e. from "hello,world,something" to "hello or world or something"
+query="${changes//,/ or }"
+```
+
+Run the test, filtered by keyword expression
+
+``` shell
+hatch run pytest -k <<< echo "$query"
+```
+
+or run the test, filtered by pytest markers
+
+``` shell
+hatch run pytest -m <<< echo "$query"
+
+```
+
 ### Options
 `--short` Useful for determining what projects has been affected by the changes in CI.
 
@@ -118,13 +185,20 @@ poetry run pytest -m <<< echo "$query"
 `--since` Useful for displaying changes since a `stable` or `release` tag.
 
 Example:
+#### Poetry
 ``` shell
 poetry poly diff --since release
 ```
 
+#### Hatch
+``` shell
+hatch run poly diff --since release
+```
+
 ## Libs
 Show info about the third-party libraries used in the workspace:
 
+### Poetry
 ``` shell
 poetry poly libs
 ```
@@ -135,6 +209,12 @@ If missing, there is a Poetry command available:
 poetry lock --directory path/to-project
 ```
 
+### Hatch
+``` shell
+hatch run poly libs
+```
+
+
 ### Options
 `--directory`
 Show info about libraries used in a specific project.
@@ -155,13 +235,18 @@ Using `--alias opencv-python=cv2` will make the command treat the alias as a thi
 ## Check
 Validates the Polylith workspace, checking for any missing dependencies (bricks and third-party libraries):
 
+### Poetry
 ``` shell
 poetry poly check
 ```
 
-This feature is built on top of the `poetry poly libs` command,
-and expects a `poetry.lock` of a project to be present.
+This feature is built on top of the `poly libs` command,
+and for expects a `poetry.lock` of a `Poetry` project to be present.
 
+### Hatch
+``` shell
+hatch run poly check
+```
 
 ### Options
 `--directory`
@@ -183,10 +268,16 @@ Using `--alias opencv-python=cv2` will make the command treat the alias as a thi
 ## Sync
 Keep projects in sync with the actual usage of bricks in source code.
 
+### Poetry
 ``` shell
 poetry poly sync
 ```
 
+### Hatch
+``` shell
+hatch run poly sync
+```
+
 This feature is useful for keeping projects in sync. The command will analyze code and add any missing bricks to the projects, including the development project.
 
 - projects: will add missing bricks to the project specific _pyproject.toml_, when imported by any of the already added bricks.

docs/configuration.md

@@ -4,7 +4,7 @@ The Polylith Workspace is configured using a __workspace.toml__ file at the root
 
 A default configuration is created when running the `poetry poly create workspace` command (see the [commands](commands.md) section).
 
-An example of a workspace configuration:
+Example of a workspace configuration:
 
 ``` toml
 [tool.polylith]

docs/dependencies.md

@@ -4,14 +4,14 @@ Each project has its own `pyproject.toml`,
 where the project-specific dependencies are defined.
 
 ## Bricks (your Python code)
-Bricks are added to the `packages` section of `[tool.poetry]`,
+Bricks are added to the `packages` section of `[tool.poetry]` or the `[tool.hatch.build.force-include]`,
 described in [Projects & pyproject.toml](projects.md).
 
 To keep a project up-to-date with needed bricks, there is a `poly sync` command available.
 Usage is described in [commands](commands.md). The command is there for convenience, you can also add the bricks manually.
 
 ## Libraries (third-party dependencies)
-The recommended workflow for Polylith is to use `poetry add` to install the needed libraries to the __Development__ `pyproject.toml`.
+The recommended workflow for Polylith is to use `poetry add`, or manually adding, to install the needed libraries to the __Development__ `pyproject.toml`.
 The Development `pyproject.toml` is located at the Workspace root.
 The Development environment should have __all__ dependencies added: all bricks and all the third-party libraries.
 The dev-dependencies (such as Mypy, Black, Flake8, Ruff etc.) are also added to the Development `pyproject.toml`.
@@ -27,6 +27,12 @@ Use the `poly libs` and/or `poly check` [command](commands.md) to verify all tha
 Both commands support the `--directory` option (coming from Poetry).
 This means that you can run the commands from the workspace root, but for a specific project:
 
+### Poetry
 ``` shell
 poetry poly check --directory projects/my-project
 ```
+
+### Hatch
+``` shell
+hatch run poly check --directory projects/my-project
+```

docs/deployment.md

@@ -1,10 +1,14 @@
 # Packaging & deploying
 
+## Poetry
 Packaging and deploying Polylith projects is done by using the Poetry Multiproject plugin command (see [installation](installation.md)).
 
 The `poetry build-project` command will make it possible to use relative package includes as how components and bases are added to Python Polylith projects. 
 Relative includes are currently not possible by default in __Poetry__, that is where the __Multiproject__ plugin comes in.
 
+## Hatch
+Hatch supports relative includes via the `force-include` configuration. Nothing extra needed!
+
 ## Packaging
 To collect the components and bases that are needed for a specific project, the tool introduces a _build_ step. 
 The tool will build a _wheel_ and an _sdist_ from the source code of a project.
@@ -13,12 +17,21 @@ This is the preferred way for Polylith projects.
 
 ### Packaging a service or app
 
+#### Poetry
 ``` shell
 poetry build-project --directory path/to/project
 ```
 
+#### Hatch
+``` shell
+cd path/to_project
+
+hatch build
+```
+
+
 This command will create a project specific _dist_ folder containing a _wheel_ and an _sdist_.
-You can use the default __poetry build__ options with this command too.
+You can use the available __build__ options with this command too.
 
 ## Deploying
 You can use the built artifacts to install your service in your preffered way, just by running
@@ -28,6 +41,11 @@ pip install the-built-artifact.whl
 ```
 
 ### Packaging a Library
+
+__NOTE:__ only supported for Poetry.
+
+_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. 

docs/ide.md

@@ -38,18 +38,30 @@ extraPaths = ["bases", "components"]
 
 ## .venv
 It is recommended to create the virtual environment locally, for a great code editor experience.
-By default, `Poetry` will create a `venv` outside of the repo. You can override that behaviour by adding a configuration in a `poetry.toml` file:
+By default, both `Poetry` and `Hatch` will create a `venv` outside of the repo.
+You can override that behaviour by adding a configuration.
+
+### Poetry
+Add this in a `poetry.toml` file:
 
 ``` toml
 [virtualenvs]
 path = ".venv"
 in-project = true
 ```
 
+### Hatch
+``` toml
+[tool.hatch.envs.default]
+type = "virtual"
+path = ".venv"
+```
+
+
 ## PyCharm
 Make sure that you have a local virtual environment configuration (see above).
 
-Run `poetry install` in a shell.
+Run `poetry install` or `hatch env create` in a shell.
 
 This will install the dependencies, and make the environment aware of the `bases` and `components` folders.
 PyCharm will ask about what interpreter to use when opening a Python file. Make sure to choose the local one in the `.venv` folder.

docs/index.md

@@ -43,7 +43,10 @@ In short, Polylith is about:
 - Keeping it simple
 
 ## Polylith for Python?
-The __Python tools for the Polylith Architecture__ is built as a __Poetry__ plugin. The plugin will add Polylith specific features to Poetry.
+The __Python tools for the Polylith Architecture__ is available as two options:
+
+- A __Poetry__ plugin. The plugin will add Polylith specific features to Poetry.
+- ⭐ New! ⭐ A standalone CLI, currently supporting __Hatch__ (and Poetry).
 
 ### Use cases
 
@@ -67,7 +70,7 @@ See [The Polylith Workspace](workspace.md) for how such a structure looks like.
 
 ![polylith developer experience](img/polylith-and-the-developer-experience.png)
 
-### It is all about the bricks
+### Simple is better
 The main takeaway is to view code as small, reusable bricks, that ideally does one thing only.
 A brick is not the same thing as a library. So, what's the difference? Well, a library is a full blown feature. A brick can be a single function, or a parser. It can also be a thin wrapper around a third party tool.
 

docs/installation.md

@@ -1,9 +1,8 @@
 # Installation
 
-## Install Poetry & plugins
-With the `Poetry` version 1.2 or later installed, you can add plugins.
-
-Add the [Multiproject](https://github.com/DavidVujic/poetry-multiproject-plugin) plugin,
+## Poetry
+### Add Poetry plugins
+With the `Poetry` version 1.2 or later installed, you can add plugins. First, add the [Multiproject](https://github.com/DavidVujic/poetry-multiproject-plugin) plugin,
 that will enable the very important __Workspace__ support to Poetry.
 ``` shell
 poetry self add poetry-multiproject-plugin
@@ -15,3 +14,8 @@ poetry self add poetry-polylith-plugin
 ```
 
 Done!
+
+## Hatch
+
+No external tools needed other than project-specific dependencies (see the [Projects & pyproject.toml](projects.md) section),
+and the (soon released) build plugin to add support for packaging libraries.