From 50eef3736945eadaef53250576af77e8d4c05833 Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Sun, 29 Jan 2023 17:23:45 +0100
Subject: [PATCH 01/11] wip(poly create with docs): create README and interface
 docstring when creating a brick

---
 components/polylith/bricks/base.py            |  6 ++---
 components/polylith/bricks/brick.py           | 12 +++++++--
 components/polylith/bricks/component.py       |  6 ++---
 components/polylith/interface/interfaces.py   | 27 ++++++++++++++++---
 components/polylith/poetry/commands/create.py |  3 ++-
 .../polylith/poetry/commands/create_base.py   |  7 +++++
 .../poetry/commands/create_component.py       |  7 +++++
 components/polylith/readme/__init__.py        |  4 +--
 components/polylith/readme/readme.py          | 25 ++++++++++++++---
 9 files changed, 79 insertions(+), 18 deletions(-)

diff --git a/components/polylith/bricks/base.py b/components/polylith/bricks/base.py
index 3b1725ad..dc39b6e8 100644
--- a/components/polylith/bricks/base.py
+++ b/components/polylith/bricks/base.py
@@ -1,5 +1,5 @@
 from pathlib import Path
-from typing import List
+from typing import List, Union
 
 from polylith.bricks import component
 from polylith.bricks.brick import create_brick
@@ -7,8 +7,8 @@
 from polylith.test import create_test
 
 
-def create_base(path: Path, namespace: str, package: str) -> None:
-    create_brick(path, bases_dir, namespace, package)
+def create_base(path: Path, namespace: str, package: str, description: Union[str, None]) -> None:
+    create_brick(path, bases_dir, namespace, package, description)
     create_test(path, bases_dir, namespace, package)
 
 
diff --git a/components/polylith/bricks/brick.py b/components/polylith/bricks/brick.py
index 14c3909f..610c7edc 100644
--- a/components/polylith/bricks/brick.py
+++ b/components/polylith/bricks/brick.py
@@ -1,17 +1,25 @@
 from pathlib import Path
+from typing import Union
 
 from polylith.dirs import create_dir
 from polylith.files import create_file
 from polylith.interface import create_interface
+from polylith.readme import create_brick_readme
 from polylith.workspace import parser
 
 
 def create_brick(
-    root: Path, brick: str, namespace: str, package: str, modulename: str = "core"
+    root: Path,
+    brick: str,
+    namespace: str,
+    package: str,
+    description: Union[str, None],
+    modulename: str = "core",
 ) -> None:
     dirs_structure = parser.get_brick_structure_from_config(root)
     dirs = dirs_structure.format(brick=brick, namespace=namespace, package=package)
     d = create_dir(root, dirs)
 
     create_file(d, f"{modulename}.py")
-    create_interface(d, namespace, package, modulename)
+    create_interface(d, namespace, package, modulename, description)
+    create_brick_readme(d, package, brick, description)
diff --git a/components/polylith/bricks/component.py b/components/polylith/bricks/component.py
index 14118802..59c99d3a 100644
--- a/components/polylith/bricks/component.py
+++ b/components/polylith/bricks/component.py
@@ -1,5 +1,5 @@
 from pathlib import Path
-from typing import List
+from typing import List, Union
 
 from polylith import workspace
 from polylith.bricks.brick import create_brick
@@ -7,8 +7,8 @@
 from polylith.test import create_test
 
 
-def create_component(path: Path, namespace: str, package: str) -> None:
-    create_brick(path, components_dir, namespace, package)
+def create_component(path: Path, namespace: str, package: str, description: Union[str, None]) -> None:
+    create_brick(path, components_dir, namespace, package, description)
     create_test(path, components_dir, namespace, package)
 
 
diff --git a/components/polylith/interface/interfaces.py b/components/polylith/interface/interfaces.py
index fd3d95c7..a362d885 100644
--- a/components/polylith/interface/interfaces.py
+++ b/components/polylith/interface/interfaces.py
@@ -1,11 +1,20 @@
 from pathlib import Path
+from typing import Union
 
 from polylith.files import create_file
 
-template = """\
+template_docstring = """\
+\"\"\"
+{description}
+\"\"\"
+
+"""
+
+template_content = """\
 from {namespace}.{package} import {modulename}
 
 __all__ = ["{modulename}"]
+
 """
 
 
@@ -15,13 +24,23 @@ def to_namespaced_path(package: str) -> str:
     return ".".join(parts)
 
 
-def create_interface(path: Path, namespace: str, package: str, modulename: str) -> None:
+def create_interface(
+    path: Path,
+    namespace: str,
+    package: str,
+    modulename: str,
+    description: Union[str, None],
+) -> None:
     interface = create_file(path, "__init__.py")
 
     package_path = to_namespaced_path(package)
 
-    content = template.format(
+    docstring = (
+        template_docstring.format(description=description) if description else ""
+    )
+
+    content = template_content.format(
         namespace=namespace, package=package_path, modulename=modulename
     )
 
-    interface.write_text(content)
+    interface.write_text(docstring + content)
diff --git a/components/polylith/poetry/commands/create.py b/components/polylith/poetry/commands/create.py
index 045c05c1..0835fd2d 100644
--- a/components/polylith/poetry/commands/create.py
+++ b/components/polylith/poetry/commands/create.py
@@ -6,6 +6,7 @@
 def create(command, fn):
     root = repo.find_workspace_root(Path.cwd())
     name = command.option("name")
+    description = command.option("description")
     namespace = workspace.parser.get_namespace_from_config(root)
 
     if not name:
@@ -16,4 +17,4 @@ def create(command, fn):
             "Didn't find a namespace. Expected to find it in workspace.toml."
         )
 
-    fn(root, namespace, name)
+    fn(root, namespace, name, description)
diff --git a/components/polylith/poetry/commands/create_base.py b/components/polylith/poetry/commands/create_base.py
index 33b81292..3cfbe5f3 100644
--- a/components/polylith/poetry/commands/create_base.py
+++ b/components/polylith/poetry/commands/create_base.py
@@ -10,6 +10,13 @@ class CreateBaseCommand(Command):
 
     options = [
         option("name", None, "Name of the base.", flag=False),
+        option(
+            "description",
+            None,
+            "Description of the base.",
+            flag=False,
+            value_required=False,
+        ),
     ]
 
     def handle(self) -> int:
diff --git a/components/polylith/poetry/commands/create_component.py b/components/polylith/poetry/commands/create_component.py
index 9d3782ac..b04cfd50 100644
--- a/components/polylith/poetry/commands/create_component.py
+++ b/components/polylith/poetry/commands/create_component.py
@@ -10,6 +10,13 @@ class CreateComponentCommand(Command):
 
     options = [
         option("name", None, "Name of the component.", flag=False),
+        option(
+            "description",
+            None,
+            "Description of the component.",
+            flag=False,
+            value_required=False,
+        ),
     ]
 
     def handle(self) -> int:
diff --git a/components/polylith/readme/__init__.py b/components/polylith/readme/__init__.py
index a23126f2..333a0cd9 100644
--- a/components/polylith/readme/__init__.py
+++ b/components/polylith/readme/__init__.py
@@ -1,3 +1,3 @@
-from polylith.readme.readme import create_workspace_readme
+from polylith.readme.readme import create_brick_readme, create_workspace_readme
 
-__all__ = ["create_workspace_readme"]
+__all__ = ["create_brick_readme", "create_workspace_readme"]
diff --git a/components/polylith/readme/readme.py b/components/polylith/readme/readme.py
index 99965b94..3250b1d2 100644
--- a/components/polylith/readme/readme.py
+++ b/components/polylith/readme/readme.py
@@ -1,8 +1,9 @@
 from pathlib import Path
+from typing import Union
 
 from polylith import log, repo
 
-template = """\
+workspace_template = """\
 # A Python Polylith repo
 
 ## Docs
@@ -13,11 +14,17 @@
 [python-polylith](https://github.com/DavidVujic/python-polylith)
 """
 
+brick_template = """\
+# {name} {brick}
+
+{description}
+"""
+
 
 logger = log.getLogger()
 
 
-def create_workspace_readme(path: Path, namespace: str) -> None:
+def create_readme(path: Path, template: str, **kwargs) -> None:
     fullpath = path / repo.readme_file
 
     if fullpath.exists():
@@ -25,4 +32,16 @@ def create_workspace_readme(path: Path, namespace: str) -> None:
         return
 
     with fullpath.open("w", encoding="utf-8") as f:
-        f.write(template.format(namespace=namespace))
+        f.write(template.format(**kwargs))
+
+
+def create_workspace_readme(path: Path, namespace: str) -> None:
+    create_readme(path, workspace_template, namespace=namespace)
+
+
+def create_brick_readme(
+    path: Path, name: str, brick: str, description: Union[str, None]
+) -> None:
+    b = "component" if brick in repo.components_dir else "base"
+
+    create_readme(path, brick_template, name=name, brick=b, description=description)

From 090d91bcef3c3098d83544ee37da9d5057c5f60c Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Sun, 29 Jan 2023 17:46:04 +0100
Subject: [PATCH 02/11] wip(poly create with docs): enable or disable the
 create README-on-poly-create feature

---
 components/polylith/bricks/brick.py     | 4 +++-
 components/polylith/workspace/create.py | 2 ++
 components/polylith/workspace/parser.py | 7 +++++++
 3 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/components/polylith/bricks/brick.py b/components/polylith/bricks/brick.py
index 610c7edc..3fa57f47 100644
--- a/components/polylith/bricks/brick.py
+++ b/components/polylith/bricks/brick.py
@@ -22,4 +22,6 @@ def create_brick(
 
     create_file(d, f"{modulename}.py")
     create_interface(d, namespace, package, modulename, description)
-    create_brick_readme(d, package, brick, description)
+
+    if parser.is_readme_generation_enabled(root):
+        create_brick_readme(d, package, brick, description)
diff --git a/components/polylith/workspace/create.py b/components/polylith/workspace/create.py
index ae7b9ab5..d2c27d3b 100644
--- a/components/polylith/workspace/create.py
+++ b/components/polylith/workspace/create.py
@@ -12,6 +12,8 @@
 
 [tool.polylith.structure]
 theme = "{theme}"
+create_brick_docs = true
+
 
 [tool.polylith.test]
 enabled = true
diff --git a/components/polylith/workspace/parser.py b/components/polylith/workspace/parser.py
index 9780c76c..e0dd952c 100644
--- a/components/polylith/workspace/parser.py
+++ b/components/polylith/workspace/parser.py
@@ -31,6 +31,13 @@ def is_test_generation_enabled(path: Path) -> bool:
     return bool(enabled)
 
 
+def is_readme_generation_enabled(path: Path) -> bool:
+    toml: dict = _load_workspace_config(path)
+
+    enabled = toml["tool"]["polylith"]["structure"].get("create_brick_docs")
+    return bool(enabled)
+
+
 def get_theme_from_config(path: Path) -> str:
     toml: dict = _load_workspace_config(path)
 

From b06e14703397c8ae24ce789475aef5fa9faf3baf Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Sun, 29 Jan 2023 18:28:58 +0100
Subject: [PATCH 03/11] wip(poly create with docs): create readme handling an
 empty description

---
 components/polylith/readme/readme.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/components/polylith/readme/readme.py b/components/polylith/readme/readme.py
index 3250b1d2..030102c1 100644
--- a/components/polylith/readme/readme.py
+++ b/components/polylith/readme/readme.py
@@ -44,4 +44,6 @@ def create_brick_readme(
 ) -> None:
     b = "component" if brick in repo.components_dir else "base"
 
-    create_readme(path, brick_template, name=name, brick=b, description=description)
+    create_readme(
+        path, brick_template, name=name, brick=b, description=description or ""
+    )

From 05f10f90f0c622c6e398dc60d646edc09521e00a Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Sun, 29 Jan 2023 20:17:42 +0100
Subject: [PATCH 04/11] wip(poly create with docs): enable or disable the
 create README-on-poly-create feature

---
 components/polylith/workspace/create.py | 2 +-
 components/polylith/workspace/parser.py | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/components/polylith/workspace/create.py b/components/polylith/workspace/create.py
index d2c27d3b..7c7bffaf 100644
--- a/components/polylith/workspace/create.py
+++ b/components/polylith/workspace/create.py
@@ -12,7 +12,7 @@
 
 [tool.polylith.structure]
 theme = "{theme}"
-create_brick_docs = true
+with_brick_docs = true
 
 
 [tool.polylith.test]
diff --git a/components/polylith/workspace/parser.py b/components/polylith/workspace/parser.py
index e0dd952c..bd196f30 100644
--- a/components/polylith/workspace/parser.py
+++ b/components/polylith/workspace/parser.py
@@ -34,7 +34,7 @@ def is_test_generation_enabled(path: Path) -> bool:
 def is_readme_generation_enabled(path: Path) -> bool:
     toml: dict = _load_workspace_config(path)
 
-    enabled = toml["tool"]["polylith"]["structure"].get("create_brick_docs")
+    enabled = toml["tool"]["polylith"]["structure"].get("with_brick_docs")
     return bool(enabled)
 
 

From c6682f30de2db925e9ac6b9711615a6604bc2dea Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Sun, 29 Jan 2023 20:20:19 +0100
Subject: [PATCH 05/11] feat(poly create with docs): bump version to 1.2.0

---
 projects/poetry_polylith_plugin/pyproject.toml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/projects/poetry_polylith_plugin/pyproject.toml b/projects/poetry_polylith_plugin/pyproject.toml
index acba05d3..83351bfb 100644
--- a/projects/poetry_polylith_plugin/pyproject.toml
+++ b/projects/poetry_polylith_plugin/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "poetry-polylith-plugin"
-version = "1.1.1"
+version = "1.2.0"
 description = "A Poetry plugin that adds tooling support for the Polylith Architecture"
 authors = ["David Vujic"]
 homepage = "https://github.com/davidvujic/python-polylith"

From 531215011962e40c135454a2ebcbb4d1e549cb44 Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Sun, 29 Jan 2023 20:24:38 +0100
Subject: [PATCH 06/11] feat(poly create with docs): docs about the
 generate-README option and the new --description flag

---
 projects/poetry_polylith_plugin/README.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/projects/poetry_polylith_plugin/README.md b/projects/poetry_polylith_plugin/README.md
index 938eea92..d6a9e533 100644
--- a/projects/poetry_polylith_plugin/README.md
+++ b/projects/poetry_polylith_plugin/README.md
@@ -51,6 +51,9 @@ Add a component:
 poetry poly create component --name my_component
 ```
 
+##### Options
+`--description` Add a component description. Will be added as a component docstring, and in the component README (if enabled with the `with_brick_docs` workspace config).
+
 Add a base:
 
 ``` shell
@@ -58,6 +61,9 @@ Add a base:
 poetry poly create base --name my_example_aws_lambda
 ```
 
+##### Options
+`--description` Add a base description. Will be added as a base docstring, and in the component README (if enabled with the `with_brick_docs` workspace config).
+
 Add a project:
 
 ``` shell
@@ -117,6 +123,7 @@ git_tag_pattern = "stable-*"
 
 [tool.polylith.structure]
 theme = "loose"
+with_brick_docs = true
 
 [tool.polylith.test]
 enabled = true

From 56af6e26ed5b0d09e28028d046fb434db4a73ba4 Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Sun, 29 Jan 2023 20:28:45 +0100
Subject: [PATCH 07/11] feat(poly create with docs): docs about the
 generate-README option and the new --description flag

---
 projects/poetry_polylith_plugin/README.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/projects/poetry_polylith_plugin/README.md b/projects/poetry_polylith_plugin/README.md
index d6a9e533..ebd05fac 100644
--- a/projects/poetry_polylith_plugin/README.md
+++ b/projects/poetry_polylith_plugin/README.md
@@ -51,9 +51,6 @@ Add a component:
 poetry poly create component --name my_component
 ```
 
-##### Options
-`--description` Add a component description. Will be added as a component docstring, and in the component README (if enabled with the `with_brick_docs` workspace config).
-
 Add a base:
 
 ``` shell
@@ -62,7 +59,8 @@ poetry poly create base --name my_example_aws_lambda
 ```
 
 ##### Options
-`--description` Add a base description. Will be added as a base docstring, and in the component README (if enabled with the `with_brick_docs` workspace config).
+`--description`
+Add a brick description. Will be added as a brick docstring, and in the brick-sprcific README (if it is enabled in the `with_brick_docs` workspace config).
 
 Add a project:
 

From 510379414e0a937f406e62948316a49206d38b35 Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Wed, 1 Feb 2023 17:34:09 +0100
Subject: [PATCH 08/11] fix(readme): create the readme in the right place for
 both themes + refactorings

---
 components/polylith/bricks/brick.py     | 13 +++++++++----
 components/polylith/workspace/parser.py |  9 +++++++++
 2 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/components/polylith/bricks/brick.py b/components/polylith/bricks/brick.py
index 3fa57f47..e08e4942 100644
--- a/components/polylith/bricks/brick.py
+++ b/components/polylith/bricks/brick.py
@@ -16,12 +16,17 @@ def create_brick(
     description: Union[str, None],
     modulename: str = "core",
 ) -> None:
-    dirs_structure = parser.get_brick_structure_from_config(root)
-    dirs = dirs_structure.format(brick=brick, namespace=namespace, package=package)
-    d = create_dir(root, dirs)
+    path_kwargs = {"brick": brick, "namespace": namespace, "package": package}
 
+    brick_structure = parser.get_brick_structure_from_config(root)
+    resources_structure = parser.get_resources_structure_from_config(root)
+
+    brick_path = brick_structure.format(**path_kwargs)
+    resources_path = resources_structure.format(**path_kwargs)
+
+    d = create_dir(root, brick_path)
     create_file(d, f"{modulename}.py")
     create_interface(d, namespace, package, modulename, description)
 
     if parser.is_readme_generation_enabled(root):
-        create_brick_readme(d, package, brick, description)
+        create_brick_readme(root / resources_path, package, brick, description)
diff --git a/components/polylith/workspace/parser.py b/components/polylith/workspace/parser.py
index bd196f30..47eaff68 100644
--- a/components/polylith/workspace/parser.py
+++ b/components/polylith/workspace/parser.py
@@ -60,3 +60,12 @@ def get_tests_structure_from_config(path: Path) -> str:
         return "test/{brick}/{namespace}/{package}"
 
     return "{brick}/{package}/test/{namespace}/{package}"
+
+
+def get_resources_structure_from_config(path: Path) -> str:
+    theme = get_theme_from_config(path)
+
+    if theme == "loose":
+        return "{brick}/{namespace}/{package}"
+
+    return "{brick}/{package}"

From 19c407b83c02a11975755d269e6c3e3f40080fd4 Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Wed, 1 Feb 2023 17:56:59 +0100
Subject: [PATCH 09/11] fix(workspace config): Brick README in a resources
 section

---
 components/polylith/workspace/create.py | 3 ++-
 components/polylith/workspace/parser.py | 4 ++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/components/polylith/workspace/create.py b/components/polylith/workspace/create.py
index 7c7bffaf..1f0b8f55 100644
--- a/components/polylith/workspace/create.py
+++ b/components/polylith/workspace/create.py
@@ -12,8 +12,9 @@
 
 [tool.polylith.structure]
 theme = "{theme}"
-with_brick_docs = true
 
+[tool.polylith.resources]
+brick_docs_enabled = false
 
 [tool.polylith.test]
 enabled = true
diff --git a/components/polylith/workspace/parser.py b/components/polylith/workspace/parser.py
index 47eaff68..485c4cae 100644
--- a/components/polylith/workspace/parser.py
+++ b/components/polylith/workspace/parser.py
@@ -34,14 +34,14 @@ def is_test_generation_enabled(path: Path) -> bool:
 def is_readme_generation_enabled(path: Path) -> bool:
     toml: dict = _load_workspace_config(path)
 
-    enabled = toml["tool"]["polylith"]["structure"].get("with_brick_docs")
+    enabled = toml["tool"]["polylith"]["resources"].get("brick_docs_enabled")
     return bool(enabled)
 
 
 def get_theme_from_config(path: Path) -> str:
     toml: dict = _load_workspace_config(path)
 
-    return toml["tool"]["polylith"]["structure"]["theme"] or "tdd"
+    return toml["tool"]["polylith"]["structure"].get("theme") or "tdd"
 
 
 def get_brick_structure_from_config(path: Path) -> str:

From dfaecbc82ac6e16e0b1c448a458b9a0d87780b05 Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Wed, 1 Feb 2023 18:10:40 +0100
Subject: [PATCH 10/11] fix(workspace config): soft-get Brick README config in
 the resources section for backwards-compatibility

---
 components/polylith/workspace/parser.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/components/polylith/workspace/parser.py b/components/polylith/workspace/parser.py
index 485c4cae..316285c1 100644
--- a/components/polylith/workspace/parser.py
+++ b/components/polylith/workspace/parser.py
@@ -34,7 +34,7 @@ def is_test_generation_enabled(path: Path) -> bool:
 def is_readme_generation_enabled(path: Path) -> bool:
     toml: dict = _load_workspace_config(path)
 
-    enabled = toml["tool"]["polylith"]["resources"].get("brick_docs_enabled")
+    enabled = toml["tool"]["polylith"].get("resources", {}).get("brick_docs_enabled")
     return bool(enabled)
 
 

From c8ca810104445ebc666ac761a334170e80f375c7 Mon Sep 17 00:00:00 2001
From: davidvujic <david@vujic.se>
Date: Wed, 1 Feb 2023 18:16:30 +0100
Subject: [PATCH 11/11] feat(brick-docs): add info about the brick-docs feature
 in the plugin README

---
 projects/poetry_polylith_plugin/README.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/projects/poetry_polylith_plugin/README.md b/projects/poetry_polylith_plugin/README.md
index ebd05fac..1c436ce6 100644
--- a/projects/poetry_polylith_plugin/README.md
+++ b/projects/poetry_polylith_plugin/README.md
@@ -60,7 +60,8 @@ poetry poly create base --name my_example_aws_lambda
 
 ##### Options
 `--description`
-Add a brick description. Will be added as a brick docstring, and in the brick-sprcific README (if it is enabled in the `with_brick_docs` workspace config).
+Add a brick description. Will be added as a docstring, and in the brick-specific README
+(if it is enabled in the `resources` section of the workspace config).
 
 Add a project:
 
@@ -121,7 +122,9 @@ git_tag_pattern = "stable-*"
 
 [tool.polylith.structure]
 theme = "loose"
-with_brick_docs = true
+
+[tool.polylith.resources]
+brick_docs_enabled = false
 
 [tool.polylith.test]
 enabled = true