Docs: clarify how to proceed after setup steps #301

Hi @DavidVujic, first of all huge thanks for introducing the Polylith architecture to the Python community and for your invaluable work on the related tooling.

Describe the bug

I recently discovered the Polylith architecture and read up about its concepts in the Clojure-focused GitBook and in your Python-focused documentation.

I wanted to try it out with a hands-on example and followed the steps in the Setup section (using uv) to create a minimal Polylith workspace.

However, I struggled to get the development workflow going in the way I expected. I'm unsure if my expectations were wrong or if some crucial steps are missing in the setup documentation to get to a fully functioning development project.

To Reproduce

Note: for reference, a repo with the workspace structure resulting from the steps below is available here.

Start in an empty directory and make sure that python and uv are available. I'm using the following versions:

$ python --version
Python 3.13.0

$ uv --version
uv 0.4.30

Then follow the steps in the setup guide:

$ uv init --name=polylith-bug-report
$ uv add --dev polylith-cli
$ uv add --dev ipython  # optional, for convenience

$ uv run poly create workspace --name bug_report --theme loose

Now edit pyproject.toml according to the instructions here by adding the following sections:

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build]
dev-mode-dirs = ["components", "bases", "development", "."]

Finally, run:

$ uv sync

Expected behavior

At this stage, I expected to be able to enter a Python console and import the bug_report module. However:

$ python -c "import bug_report"

Traceback (most recent call last):
  File "<string>", line 1, in <module>
    import bug_report
ModuleNotFoundError: No module named 'bug_report'

It turns out that if I create a new component then the import does work:

$ uv run poly create component --name dummy

$ python -c "import bug_report; print(bug_report is not None)"
True

However, this is quite nonintuitive. It actually took me quite a few attempts of debugging and experimenting with different things to realise that this was all that's needed.

I'm still not sure if I'm missing any further setup steps, for example in order to get the development project fully set up and working. I have included a couple of my open questions below.

Desktop (please complete the following information):

• OS: Mac OS 10.14.6
• Python version: 3.13.0
• Uv version: 0.4.30

Additional context / Further questions

As indicated above, I'm not sure whether completing the setup steps is sufficient for a fully working Polylith workspace. Open questions:

1. The docs section on Projects & pyproject.toml mentions that the project-specific pyproject.toml files need hatch-polylith-bricks as an additional build system dependency, and also require the section [tool.hatch.build.hooks.polylith-bricks] to be present (even if it is empty). Is this also necessary to set up the development project in the toplevel pyproject.toml file?

2. Do I need to run poly sync to complete the workspace setup? If I do this (after creating the dummy component above), the following section is added to the toplevel pyproject.toml file:

   [tool.polylith.bricks]
    "components/bug_report/dummy" = "bug_report/dummy"

   However, I think that I can import new components (and presumably bases, although I haven't tried this) without this section being present. Does it make a difference?

Many thanks for reading and any clarifications!