wip(poly create with docs): create README and interface docstring whe…

…n 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

components/polylith/bricks/base.py

@@ -1,14 +1,14 @@
 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
 from polylith.repo import bases_dir
 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)
 
 

components/polylith/bricks/brick.py

@@ -1,17 +1,32 @@
 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)
+    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)
+    create_interface(d, namespace, package, modulename, description)
+
+    if parser.is_readme_generation_enabled(root):
+        create_brick_readme(root / resources_path, package, brick, description)

components/polylith/bricks/component.py

@@ -1,14 +1,14 @@
 from pathlib import Path
-from typing import List
+from typing import List, Union
 
 from polylith import workspace
 from polylith.bricks.brick import create_brick
 from polylith.repo import components_dir
 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)
 
 

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)

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)

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:

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:

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"]

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,16 +14,36 @@
 [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():
         logger.info(f"A {repo.readme_file} already exists. Skipping this step.")
         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 or ""
+    )

components/polylith/workspace/create.py

@@ -13,6 +13,9 @@
 [tool.polylith.structure]
 theme = "{theme}"
 
+[tool.polylith.resources]
+brick_docs_enabled = false
+
 [tool.polylith.test]
 enabled = true
 """

components/polylith/workspace/parser.py

@@ -31,10 +31,17 @@ 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"].get("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:
@@ -53,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}"

projects/poetry_polylith_plugin/README.md

@@ -58,6 +58,11 @@ Add a base:
 poetry poly create base --name my_example_aws_lambda
 ```
 
+##### Options
+`--description`
+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:
 
 ``` shell
@@ -118,6 +123,9 @@ git_tag_pattern = "stable-*"
 [tool.polylith.structure]
 theme = "loose"
 
+[tool.polylith.resources]
+brick_docs_enabled = false
+
 [tool.polylith.test]
 enabled = true
 ```

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"