Hello -- thanks for putting together the polylith repo here as a reference. I started to use it for a small project to create a client library around an API, and also create a singer tap for that api.

One thing I found myself wanting to do is create more than one namespace underneath the components/ and bases/ directories. I'm not sure if this is supported or encouraged at this time, both because the workspace.toml at the top level looks like it wants a single value for tool.polylith.namespace, and if I try to run poetry poly create workspace --name my_new_namespace --theme loose again, I get the following error: [Errno 17] File exists: '/Users/britz/myprojects/simple-garden/bases'.

Is creating multiple namespaces discouraged? Am I thinking about something the wrong way when I want to be able to do that?

Is your feature request related to a problem? Please describe. Working through an example I am finding myself wanting to add a README.md to each component and base (and possibly also project) to make the documentation a bit easier.

Describe the solution you'd like By default it would be nice if the new folder when you do poetry poly create ... added a README.md with the name of the brick as the title. It could be set up as a feature that can be switched on an off in the config.

Describe alternatives you've considered I can of course do this manually. It's a useful prompt and feature though I think makes the scope of a brick clearer if you can document it in the directory itself.

Here is an example of a README.md I found myself writing for one of my bricks

# fetch_data component

This is a simple component that simulates fetching data from an external API. Specifically the current implementation here uses the Faker library to create some geo positioning data for each fetch call.

Closing this issue. Please reopen if the feature added doesn't work as expected. 🙏

This is now added in the Plugin, from version 1.2.1 and is published to PyPI.

To enable creation of a README.md for bricks (both bases and components), add this new config section to the workspace.toml file:

[tool.polylith.resources]
brick_docs_enabled = true

In addition to that, there is a --description option available for the poly create commands, that will add a description to the brick interfaces (the init.py module). The passed in description will also be added to the README, if it is enabled.

fix(create-project): the new description feature caused create project to fail (#51)

• fix(create project): missing description parameter to the create command + description option

• docs(description): add docs about the description option to also include projects

• bump version to 1.2.1

Description

The new description feature, released in v1.2.0 #50, caused create project to fail.

This PR will fix that, and also enable the --description option into pyproject.toml files.

Types of changes

• [x] Bug fix (non-breaking change which fixes an issue)
• [ ] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

• [x] I have read the code of conduct.
• [x] I have read the contributing guide.
• [x] I have updated the documentation accordingly (if applicable).

Description

The new description feature, released in v1.2.0 #50, caused create project to fail.

This PR will fix that, and also enable the --description option into pyproject.toml files.

Types of changes

• [x] Bug fix (non-breaking change which fixes an issue)
• [ ] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

• [x] I have read the code of conduct.
• [x] I have read the contributing guide.
• [x] I have updated the documentation accordingly (if applicable).

wip(poly create with docs): create README and interface docstring when creating a brick (#50)

• wip(poly create with docs): create README and interface docstring when creating a brick

• wip(poly create with docs): enable or disable the create README-on-poly-create feature

• wip(poly create with docs): create readme handling an empty description

• wip(poly create with docs): enable or disable the create README-on-poly-create feature

• fix(workspace config): Brick README in a resources section

• feat(poly create with docs): bump version to 1.2.0

• feat(poly create with docs): docs about the generate-README option and the new --description flag

• feat(brick-docs): add info about the brick-docs feature in the plugin README

Description

New feature:

• creating a README when creating a component or a base, this is configurable in workspace.toml
• Adding a brick docstring when passing in a --description with the poly create command

Motivation and Context

Solves suggestions in #48

How Has This Been Tested?

CircleCI ✅ Manual tests: Installed locally and created components and bricks with the brick-docs config enabled and disabled. Tested for both "tdd" and "loose" theme.

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

• [x] I have read the code of conduct.
• [x] I have read the contributing guide.
• [x] I have updated the documentation accordingly (if applicable).

feat(brick-docs): add info about the brick-docs feature in the plugin README

fix(workspace config): soft-get Brick README config in the resources section for backwards-compatibility

fix(workspace config): Brick README in a resources section

fix(readme): create the readme in the right place for both themes + refactorings

Good idea! How about the pythondev slack? I've 👋 and mentioned Polylith in the architecture channel there. Did the same on the python discord in the "software design" channel.

My current plans for the next week or so is to add a new command that I think will help out with keeping track on third-party dependencies. It's somewhere between the Clojure "poly deps" and "poly libs" commands, and I will probably add it in a newpoetry poly libs command. I also plan to add generated READMEs according to your suggestions within a day or two.

When those are published, I will record a short video and write a blog post about it too.

Next up I had an idea of a "migrate to Polylith" guide, and initially had an idea of migrating an existing Python RealWorld app to Polylith - something similar to what Furkan Bayaktar has done in Clojure.

I want to test out if my assumptions about migrating Python code are correct:

• creating a new blank Polylith workspace
• create a new base
• put an existing codebase in the base
• create a new project, extract the project configuration and put them in the project folder.
• Build the project, to make sure everything works as expected
• Begin the actual migration: move parts of the existing app into components

There's docs and info spread out in blog posts, repos and videos, and long term I would like to have something similar to the official Polylith gitbook (not necessarily that technology, could be something else).

Here's some posts that I have written and that probably could be used in a "book" about Python Polylith: About organizing code into smaller parts, aka components: https://davidvujic.blogspot.com/2022/08/a-simple-scalable-python-project.html

Overview and introduction about Polylith for Python: https://davidvujic.blogspot.com/2022/11/the-last-python-architecture-you-will-ever-need.html https://davidvujic.blogspot.com/2022/02/a-fresh-take-on-monorepos-in-python.html

If I may, I would very much like to share and spread your tutorial! And I would very much appreciate ideas and feedback as you already do about real-world usage of Polylith. I have experience in a long-term project for Clojure, and also a single-project built up with components in Python. But not really an all-in Polylith Python app.

I also like your way of using Jypyter notebooks for the development, I have not used notebooks (yet) but it looks very nice.

⭐ This is awesome! ⭐ Many thanks for this ❤️

I think a guide like this is very valuable for those new to Polylith in general, and how to use it in Python.

feat(poly create with docs): docs about the generate-README option and the new --description flag

feat(poly create with docs): bump version to 1.2.0

feat(poly create with docs): docs about the generate-README option and the new --description flag

wip(poly create with docs): enable or disable the create README-on-poly-create feature

wip(poly create with docs): create readme handling an empty description

wip(poly create with docs): enable or disable the create README-on-poly-create feature

Description

• creating a README when creating a component or a base. TODO: probably should make this behavior configurable.
• Adding a brick docstring when passing in a --description with the poly create command

Motivation and Context

Solves suggestions in #48

How Has This Been Tested?

TODO

Types of changes

• [ ] Bug fix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist:

• [x] I have read the code of conduct.
• [x] I have read the contributing guide.
• [ ] I have updated the documentation accordingly (if applicable).