Blank README.md in each new brick on create

[ttamg]

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.

[ttamg]

Perhaps I should have put this in the poetry plugin repo . Apologies if so.

[DavidVujic]

Great idea!

This would be simple to add, and I agree it probably should be configurable.

As an alternative, would a doc-string in the interface of the component (the __init__.py file) be useful? I'm thinking it could be useful in a future or extended poly command - to extract the docs from there and output in the terminal.

Something like:

"""
This is a simple component that does x and y ...
"""
from my_component.my_module import my_function

__all__ = ["my_function"]

[ttamg]

Nice idea. From my perspective:

Pros - If this could then be pulled out into some docs nice and easily then this would be helpful yes, particularly if we can also pull out the interface in the __all__ for some dynamic docs. So that would be something like the autodoc in sphinx that documents from doc strings.

Cons of a doc string, I think someone looking at the codebase in GitHub is more likely to look at a README.md than clicking into an __init__.py (which are often empty) and find the explanation.

[DavidVujic]

I think what you are writing makes a lot sense and will add the possibility to create a README when creating a component or base. Thank you for the idea and input! ⭐

[ttamg]

As an alternative, would a doc-string in the interface of the component (the __init__.py file) be useful? I'm thinking it could be useful in a future or extended poly command - to extract the docs from there and output in the terminal.

This suggestion that you can then lift it into poetry poly is quite important I think when I reflect a bit more. Leaning heavily on a tool like poetry poly as your framework tool is not something that I think the python community usually does. As someone who writes a lot of Python, I would tend to understand the structure of my modules by looking at the codebase rather than naturally reaching for a tool like poetry poly info to do it. So that requires a few behaviour changes. I think using the tool is a good idea and the way to do it so perhaps your doc strings idea would perhaps get people using the tool a lot more. Just a thought.

I really like this framework. Will try using it a bit more.👷‍♂️

[DavidVujic]

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.

[DavidVujic]

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