Merge pull request #13 from DavidVujic/add-maturin-docs

Add docs about Maturin

Author: DavidVujic

docs/commands.md

@@ -30,6 +30,15 @@ rye run poly create workspace --name my_example_namespace --theme loose
 uv run poly create workspace --name my_example_namespace --theme loose
 ```
 
+#### Maturin
+
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+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.
@@ -78,6 +87,14 @@ rye run poly create component --name my_example_component
 uv run poly create component --name my_example_component
 ```
 
+#### Maturin
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+poly create component --name my_example_component
+```
+
 ### Options
 `--name` (required) the name of the component.
 
@@ -112,6 +129,14 @@ rye run poly create base --name my_example_base
 uv run poly create base --name my_example_base
 ```
 
+#### Maturin
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+poly create base --name my_example_base
+```
+
 ### Options
 `--name` (required) the name of the base.
 
@@ -146,6 +171,14 @@ rye run poly create project --name my_example_project
 uv run poly create project --name my_example_project
 ```
 
+#### Maturin
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+poly create project --name my_example_project
+```
+
 ### Options
 `--name` (required) the name of the project.
 
@@ -180,11 +213,26 @@ rye run poly info
 uv run poly info
 ```
 
+#### Maturin
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+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:
+Shows what has changed since the most recent stable point in time.
+
+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 the Workspace [configuration](configuration.md).
+
+The `diff` command is useful in a CI environment, to determine if a project should be deployed or not.
+It is also useful when running tests for changed bricks only.
 
 #### Poetry
 ``` shell
@@ -211,37 +259,12 @@ rye run poly diff
 uv 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 the Workspace [configuration](configuration.md).
-
-The `diff` command is useful in a CI environment, to determine if a project should be deployed or not.
-It is also useful when running tests for changed bricks only.
-
-Example:
-#### Poetry
-``` shell
-poetry poly diff --since release
-```
-
-#### Hatch
-``` shell
-hatch run poly diff --since release
-```
-
-#### PDM
-``` shell
-pdm run poly diff --since release
-```
-
-#### Rye
+#### Maturin
 ``` shell
-rye run poly diff --since release
-```
+# if not already activated a virtual environment
+source .venv/bin/activate
 
-#### Rye
-``` shell
-uv run poly diff --since release
+poly diff
 ```
 
 ### Options
@@ -289,6 +312,14 @@ rye run poly libs
 uv run poly libs
 ```
 
+#### Maturin
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+poly libs
+```
+
 ### Options
 `--directory`
 Show info about libraries used in a specific project.
@@ -337,6 +368,14 @@ rye run poly check
 uv run poly check
 ```
 
+#### Maturin
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+poly check
+```
+
 ### Options
 `--directory`
 Show info about libraries used in a specific project.
@@ -383,6 +422,14 @@ rye run poly sync
 uv run poly sync
 ```
 
+#### Maturin
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+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.
@@ -421,6 +468,14 @@ rye run poly deps
 uv run poly deps
 ```
 
+#### Maturin
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+poly deps
+```
+
 ### Options
 `--directory`
 Show brick depencencies for a specific project.
@@ -540,3 +595,30 @@ or run the test, filtered by pytest markers
 ``` shell
 uv run pytest -m <<< echo "$query"
 ```
+
+#### Maturin
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+```
+
+``` shell
+# store the comma-separated list of bricks in a bash variable
+changes="$(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
+pytest -k <<< echo "$query"
+```
+
+or run the test, filtered by pytest markers
+
+``` shell
+pytest -m <<< echo "$query"
+```

docs/dependencies.md

@@ -51,3 +51,11 @@ rye run poly check --directory projects/my-project
 ``` shell
 uv run poly check --directory projects/my-project
 ```
+
+### Maturin
+``` shell
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+poly check --directory projects/my-project
+```

docs/deployment.md

@@ -28,6 +28,12 @@ packages = ["<your top namespace here>"]
 includes = ["<your top namespace here>/"]
 ```
 
+#### Maturin
+``` toml
+[tool.maturin]
+include = ["<your top namespace here>/**/*"]
+```
+
 ## 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.
@@ -67,6 +73,20 @@ rye build --wheel
 uv build --wheel projects/the_project
 ```
 
+#### Maturin
+``` shell
+cd projects/the_project
+
+# if not already activated a virtual environment
+source .venv/bin/activate
+
+poly build setup
+
+maturin build
+
+poly build teardown
+```
+
 This command will create a project specific _dist_ folder containing a _wheel_ with all the needed bricks.
 
 ## Deploying
@@ -94,7 +114,7 @@ The `build-project` command, with a custom top namespace:
 poetry build-project --with-top-namespace my_custom_namespace
 ```
 
-#### Hatch, PDM, Rye and uv
+#### uv, Hatch, PDM, Rye and Maturin
 A custom top namespace is defined in the project-specific `pyproject.toml`:
 
 ``` toml

docs/installation.md

@@ -1,3 +1,4 @@
+
 # Installation
 
 ## Poetry
@@ -15,7 +16,7 @@ poetry self add poetry-polylith-plugin
 
 Done!
 
-## Hatch, PDM, Rye, Pantsbuild and uv
+## uv, Hatch, PDM, Rye, Pantsbuild and Maturin
 
 No globally added tools needed. Add the project-specific dependencies (see the [Setup](setup.md) and [Projects & pyproject.toml](projects.md) section),
 and the build hook plugins to add support for the Polylith structure and when packaging libraries.

docs/migrating.md

@@ -20,7 +20,7 @@ packages = [
 # insert the needed 3rd party libraries here
 ```
 
-## Hatch, PDM, Rye and uv
+## uv, Hatch, PDM, Rye and Maturin
 ``` toml
 [project]
 dependencies = [] # insert the needed 3rd party libraries here
@@ -76,7 +76,18 @@ rye build --sdist
 ``` shell
 cd path/to_project
 
-uvx --from build pyproject-build --installer uv
+uv build
+```
+
+### Maturin
+``` shell
+cd path/to_project
+
+poly build setup
+
+maturin build
+
+poly build teardown
 ```
 
 The output is a `wheel` and, more importantly, an `sdist` (a source distribution). It is essentially a _zip_ file containing all source code used in the project.

docs/projects.md

@@ -203,3 +203,42 @@ Polylith bricks are added in the `[tool.polylith.bricks]` 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.
+
+
+## Maturin
+
+### The pyproject.toml in the Workspace (i.e. the one in the root folder)
+Add the `polylith-cli` to the workspace `pyproject.toml` configuration.
+
+``` toml
+[project.optional-dependencies]
+tests = [
+    "polylith-cli",
+]
+```
+
+Make Maturin aware of the way Polylith organizes source code:
+``` toml
+[tool.maturin]
+dev-mode-dirs = ["components", "bases", "development", "."]
+```
+
+
+### The project-specific pyproject.toml file(s)
+Prepare the project top folder for building wheels and sdists, by include the top namespace.
+``` toml
+[tool.maturin]
+include = ["my_namespace/**/*"]
+```
+
+Polylith bricks are added in the `[tool.polylith.bricks]` section:
+
+``` 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"
+```
+
+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.