From 7148d24fcfa395d6b04762b861a8683a22d72d89 Mon Sep 17 00:00:00 2001 From: Chris Arderne Date: Tue, 20 Aug 2024 20:14:27 +0100 Subject: [PATCH] update docs --- README.md | 28 ++++++++++++++++++++-------- docs/build.md | 2 +- docs/index.md | 16 ++++++++-------- docs/install.md | 2 +- docs/style-modules.md | 2 +- docs/style-packages.md | 2 +- 6 files changed, 32 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index a975bcf..7e8dc74 100644 --- a/README.md +++ b/README.md @@ -20,31 +20,31 @@ -Una is a tool to make Python monorepos with Rye easier. It is a CLI tool and a build plugin that does the following things: +Una is a tool to make Python monorepos easier. It is a CLI tool and a build plugin that does the following things: 1. Enable builds of individual apps or projects within a monorepo. 2. Ensure that internal and external dependencies are correctly specified. -Una is inspired by [python-polylith](https://github.com/DavidVujic/python-polylith) and borrows extensively from that codebase. -But I find the [Polylith](https://polylith.gitbook.io/polylith) architecture to be quite intimidating for many, so wanted to create a lighter touch alternative that doesn't require too much re-thinking. -This project has very limited ambitions and doesn't try to do everything a proper build system such as [Bazel](https://bazel.build/) or [Pants](https://www.pantsbuild.org/) does. -It just tries to make a simple monorepo build just about possible. +Una doesn't try to replicate a full build system such as [Bazel](https://bazel.build/) or [Pants](https://www.pantsbuild.org/). It just makes it possible to have a simple monorepo with interdependencies. Una allows two directory structures or styles: -- `packages`: this is the default style, that is just some extra build help on top of a Rye workspace. -- `modules`: a more novel approach with just a single pyproject.toml, arguably better DevX and doesn't require a Rye workspace. + +- **Packages:** The default style, where each lib or app is a package with its own pyproject.toml (much like Rust's workspaces). +- **Modules**: A more novel approach with just a single pyproject.toml, inspired by [python-polylith](https://github.com/DavidVujic/python-polylith). Within this context, we use the following words frequently: - `lib`: a module or package that will be imported but not run. - `app`: a module or package that will be run but never imported. -- `project`: a package with no code but only dependencies (only used in the `modules` style) +- `project`: a package with no code but only dependencies (only used in the Modules style). Currently it works with the following build backends, but more will follow: - [Hatch](https://hatch.pypa.io) (used by default and and in all documentation) - [PDM](https://pdm-project.org/) +All instructions and examples use Rye for local development, but there is nothing inherently Rye-specific about the tool. + ## Examples You can see examples for each of the two styles here: @@ -163,5 +163,17 @@ It covers additional things like: - more detail on the [packages](https://una.rdrn.me/style-packages/) vs [modules](https://una.rdrn.me/style-modules/) styles - and more! +## Contributing +See the instructions at the [official documentation](https://una.rdrn.me/contributing/). + +Very briefly, local development is with Rye: +```bash +rye sync +rye run all # will fmt, lint, typecheck and test +``` + +Then open a PR. + ## License Una is distributed under the terms of the MIT license. +Significant parts of the code are from the [python-polylith](https://github.com/DavidVujic/python-polylith) project (c) 2022 David Vujic diff --git a/docs/build.md b/docs/build.md index 7df9a85..6e330ad 100644 --- a/docs/build.md +++ b/docs/build.md @@ -18,4 +18,4 @@ rye run build ``` You'll get some `*.whl` files, which you can then deploy with Docker or whatever you prefer. -They are fully self-contained, so you don't need Rye or Una or anything else wherever you want to install them. +They are fully self-contained, so you don't need Hatch/Rye/PDM or Una or anything else wherever you want to install them. diff --git a/docs/index.md b/docs/index.md index ae708f6..67e97a2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -20,31 +20,31 @@ -Una is a tool to make Python monorepos with Rye easier. It is a CLI tool and a build plugin that does the following things: +Una is a tool to make Python monorepos easier. It is a CLI tool and a build plugin that does the following things: 1. Enable builds of individual apps or projects within a monorepo. 2. Ensure that internal and external dependencies are correctly specified. -Una is inspired by [python-polylith](https://github.com/DavidVujic/python-polylith) and borrows extensively from that codebase. -But I find the [Polylith](https://polylith.gitbook.io/polylith) architecture to be quite intimidating for many, so wanted to create a lighter touch alternative that doesn't require too much re-thinking. -This project has very limited ambitions and doesn't try to do everything a proper build system such as [Bazel](https://bazel.build/) or [Pants](https://www.pantsbuild.org/) does. -It just tries to make a simple monorepo build just about possible. +Una doesn't try to replicate a full build system such as [Bazel](https://bazel.build/) or [Pants](https://www.pantsbuild.org/). It just makes it possible to have a simple monorepo with interdependencies. Una allows two directory structures or styles: -- `packages`: this is the default style, that is just some extra build help on top of a Rye workspace. -- `modules`: a more novel approach with just a single pyproject.toml, arguably better DevX and doesn't require a Rye workspace. + +- **Packages:** The default style, where each lib or app is a package with its own pyproject.toml (much like Rust's workspaces). +- **Modules**: A more novel approach with just a single pyproject.toml, inspired by [python-polylith](https://github.com/DavidVujic/python-polylith). Within this context, we use the following words frequently: - `lib`: a module or package that will be imported but not run. - `app`: a module or package that will be run but never imported. -- `project`: a package with no code but only dependencies (only used in the `modules` style) +- `project`: a package with no code but only dependencies (only used in the Modules style). Currently it works with the following build backends, but more will follow: - [Hatch](https://hatch.pypa.io) (used by default and and in all documentation) - [PDM](https://pdm-project.org/) +All instructions and examples use Rye for local development, but there is nothing inherently Rye-specific about the tool. + ## Examples You can see examples for each of the two styles here: diff --git a/docs/install.md b/docs/install.md index 071509f..dd192bb 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,7 +4,7 @@ But you will likely struggle to manage your monorepo without the tool! So you may as well install it: ```bash -rya add --dev una +rye add --dev una ``` As for the build-time `hatch-una`, it will automatically be installed by build tools when it spots this in your `pyproject.toml` (this will be configured automatically by the CLI): diff --git a/docs/style-modules.md b/docs/style-modules.md index 6318539..6eed6bd 100644 --- a/docs/style-modules.md +++ b/docs/style-modules.md @@ -4,7 +4,7 @@ You can see an example of the Modules style here: - [una-example-modules](https://github.com/carderne/una-example-modules) This approach is inspired by [Polylith](https://davidvujic.github.io/python-polylith-docs/). -You don't use a Rye workspace (and indeed this approach will work with just Hatch), and there's only a single `pyproject.toml`. +Each app or lib is just a module with no pyproject.toml. The structure looks like this: ```bash diff --git a/docs/style-packages.md b/docs/style-packages.md index e107e9a..5206adc 100644 --- a/docs/style-packages.md +++ b/docs/style-packages.md @@ -3,7 +3,7 @@ You can see an example of the Modules style here: - [una-example-packages](https://github.com/carderne/una-example-packages) -In this setup, we use Rye's built-in workspace support. The structure will look something like this: +In this setup, we use Rye's built-in workspace support (but you could also just create this structure some other way, YMMV). The structure will look something like this: ```bash . ├── pyproject.toml