feat: better monorepo support by allowing python package to sit in a subfolder

Author: jensens

CHANGES.md

@@ -5,6 +5,12 @@
 - Enhancement: Use tables in the generated sphinx code for topic/domains.
   [jensens, 02-11-2025]
 
+- Feature: Add monorepo support with `PROJECT_PATH_PYTHON` setting.
+  Python projects can now be located in subdirectories while keeping the Makefile at the repository root. Includes auto-detection of `pyproject.toml` in subdirectories on init, `--project-path-python` CLI flag and preseed file support.
+  Useful for monorepos with multiple applications (e.g., frontend + backend).
+  See the "Monorepo Support" section in getting-started.md for details.
+  [jensens, 02-11-2025]
+
 ## 2.0.0 (2025-10-24)
 
 - **Breaking**: Drop Python 3.9 support. Minimum Python version is now 3.10.

Makefile

@@ -42,6 +42,13 @@ INCLUDE_MAKEFILE?=include.mk
 # No default value.
 EXTRA_PATH?=
 
+# Path to Python project relative to Makefile (repository root).
+# Leave empty if Python project is in the same directory as Makefile.
+# For monorepo setups, set to subdirectory name (e.g., `backend`).
+# Future-proofed for multi-language monorepos (e.g., PROJECT_PATH_NODEJS).
+# No default value.
+PROJECT_PATH_PYTHON?=
+
 ## core.mxenv
 
 # Primary Python interpreter to use. It is used to create the
@@ -53,8 +60,8 @@ EXTRA_PATH?=
 PRIMARY_PYTHON?=3.14
 
 # Minimum required Python version.
-# Default: 3.9
-PYTHON_MIN_VERSION?=3.9
+# Default: 3.10
+PYTHON_MIN_VERSION?=3.10
 
 # Install packages using the given package installer method.
 # Supported are `pip` and `uv`. When `uv` is selected, a global installation
@@ -194,6 +201,9 @@ FORMAT_TARGETS?=
 
 export PATH:=$(if $(EXTRA_PATH),$(EXTRA_PATH):,)$(PATH)
 
+# Helper variable: adds trailing slash to PROJECT_PATH_PYTHON only if non-empty
+PYTHON_PROJECT_PREFIX=$(if $(PROJECT_PATH_PYTHON),$(PROJECT_PATH_PYTHON)/,)
+
 # Defensive settings for make: https://tech.davis-hansson.com/p/make/
 SHELL:=bash
 .ONESHELL:
@@ -474,7 +484,7 @@ else
 	@echo "[settings]" > $(PROJECT_CONFIG)
 endif
 
-LOCAL_PACKAGE_FILES:=$(wildcard pyproject.toml setup.cfg setup.py requirements.txt constraints.txt)
+LOCAL_PACKAGE_FILES:=$(wildcard $(PYTHON_PROJECT_PREFIX)pyproject.toml $(PYTHON_PROJECT_PREFIX)setup.cfg $(PYTHON_PROJECT_PREFIX)setup.py $(PYTHON_PROJECT_PREFIX)requirements.txt $(PYTHON_PROJECT_PREFIX)constraints.txt)
 
 FILES_TARGET:=requirements-mxdev.txt
 $(FILES_TARGET): $(PROJECT_CONFIG) $(MXENV_TARGET) $(SOURCES_TARGET) $(LOCAL_PACKAGE_FILES)

docs/source/getting-started.md

@@ -91,6 +91,99 @@ Both methods create:
 
 To update an existing Makefile without interactive prompts, run `mxmake update`.
 
+## Monorepo Support
+
+mxmake supports monorepo setups where your Python project lives in a subdirectory while the Makefile stays at the repository root. This is useful when you have multiple applications (e.g., frontend + backend) in one repository.
+
+### Example Directory Structure
+
+```
+myrepo/                    # Repository root
+├── Makefile               # Generated by mxmake (at root)
+├── mx.ini                 # mxdev config (at root)
+├── .venv/                 # Virtual environment (at root)
+├── .mxmake/               # Generated files (at root)
+├── sources/               # mxdev packages (at root)
+├── frontend/              # Frontend application
+│   └── package.json
+└── backend/               # Python project in subdirectory
+    ├── pyproject.toml
+    ├── src/
+    │   └── myapp/
+    └── tests/
+```
+
+### Setup Methods
+
+#### Method 1: Auto-detection (Recommended)
+
+If `pyproject.toml` is in a subdirectory, mxmake will detect it automatically:
+
+```shell
+cd myrepo
+uvx mxmake init
+# mxmake will prompt: "Use 'backend' as PROJECT_PATH_PYTHON? (Y/n)"
+```
+
+#### Method 2: CLI Flag
+
+Specify the project path explicitly:
+
+```shell
+uvx mxmake init --project-path-python backend
+```
+
+#### Method 3: Preseed File
+
+Include in your preseed YAML:
+
+```yaml
+topics:
+  core:
+    base:
+      PROJECT_PATH_PYTHON: backend
+```
+
+Then run:
+
+```shell
+uvx mxmake init --preseeds preseed.yaml
+```
+
+### What Happens
+
+When `PROJECT_PATH_PYTHON` is set:
+
+1. **Makefile**: References Python package files with the correct path
+   - Looks for `backend/pyproject.toml` instead of `./pyproject.toml`
+
+2. **mx.ini**: Configure test/coverage paths relative to repository root
+   - Set `mxmake-test-path = backend/tests` and `mxmake-source-path = backend/src`
+
+3. **GitHub Actions**: Cache uses correct path
+   - `cache-dependency-glob: "backend/pyproject.toml"`
+
+### Configuration
+
+The `PROJECT_PATH_PYTHON` setting appears in your Makefile:
+
+```makefile
+# Path to Python project relative to Makefile (repository root)
+PROJECT_PATH_PYTHON?=backend
+```
+
+In your `mx.ini`, specify paths relative to the repository root (including the project path):
+
+```ini
+[settings]
+mxmake-test-path = backend/tests
+mxmake-source-path = backend/src
+```
+
+```{important}
+Future-proofing: This setting is named `PROJECT_PATH_PYTHON` to allow for future `PROJECT_PATH_NODEJS` support in multi-language monorepos.
+```
+
 ## How to change the settings
 
 The `Makefile` consists of three sections:

docs/source/migration.md

@@ -4,7 +4,56 @@ This guide documents breaking changes between mxmake versions and how to migrate
 
 ## Version 2.0.1 (unreleased)
 
-**No breaking changes**
+### Added: Monorepo Support
+
+**New Feature**: Python projects can now be located in a subdirectory relative to the Makefile.
+
+**Purpose**: Support monorepo setups with multiple applications (e.g., frontend + backend) in one repository.
+
+**New Setting**: `PROJECT_PATH_PYTHON` in the `core.base` domain.
+
+**Example Configuration**:
+```makefile
+# In your Makefile
+PROJECT_PATH_PYTHON?=backend
+```
+
+```ini
+# In your mx.ini (specify full paths from repo root)
+[settings]
+mxmake-test-path = backend/tests
+mxmake-source-path = backend/src
+```
+
+**Setup Methods**:
+
+1. **Auto-detection** (recommended):
+   ```shell
+   uvx mxmake init
+   # Prompts if pyproject.toml found in subdirectory
+   ```
+
+2. **CLI flag**:
+   ```shell
+   uvx mxmake init --project-path-python backend
+   ```
+
+3. **Preseed file**:
+   ```yaml
+   topics:
+     core:
+       base:
+         PROJECT_PATH_PYTHON: backend
+   ```
+
+**What Changes**:
+- Makefile references: `backend/pyproject.toml` instead of `./pyproject.toml`
+- mx.ini paths: Specify full paths from repository root (e.g., `mxmake-test-path = backend/tests`)
+- GitHub Actions: Cache uses `backend/pyproject.toml` for dependency tracking
+
+**Migration**: None required. This is an opt-in feature with no impact on existing projects.
+
+**See Also**: [Monorepo Support](getting-started.html#monorepo-support) in Getting Started guide.
 
 ## Version 2.0.0 (2025-10-24)
 

src/mxmake/main.py

@@ -234,7 +234,7 @@ def create_config(prompt: bool, preseeds: dict[str, typing.Any] | None):
         if yn not in ["n", "N"]:
             factory = template.lookup("mx.ini")
             mx_ini_template = factory(
-                target_folder, domains, get_template_environment()
+                target_folder, domains, get_template_environment(), domain_settings
             )
             mx_ini_template.write()
     elif not prompt and not preseeds and not (target_folder / "mx.ini").exists():
@@ -244,7 +244,7 @@ def create_config(prompt: bool, preseeds: dict[str, typing.Any] | None):
     elif preseeds and "mx-ini" in preseeds and not (target_folder / "mx.ini").exists():
         sys.stdout.write("Generate mx configuration file\n")
         factory = template.lookup("mx.ini")
-        mx_ini_template = factory(target_folder, domains, get_template_environment())
+        mx_ini_template = factory(target_folder, domains, get_template_environment(), domain_settings)
         mx_ini_template.write()
     else:
         sys.stdout.write(
@@ -266,12 +266,28 @@ def create_config(prompt: bool, preseeds: dict[str, typing.Any] | None):
             )
             for template_name in ci_choice["ci"]:
                 factory = template.lookup(template_name)
-                factory(get_template_environment()).write()
+                factory(get_template_environment(), domain_settings).write()
     elif preseeds and "ci-templates" in preseeds:
         for template_name in preseeds["ci-templates"]:
             sys.stdout.write(f"Generate CI file from {template_name} template\n")
             factory = template.lookup(template_name)
-            factory(get_template_environment()).write()
+            factory(get_template_environment(), domain_settings).write()
+
+
+def auto_detect_project_path_python() -> str | None:
+    """Auto-detect Python project in subdirectories if not in current directory."""
+    cwd = Path.cwd()
+
+    # Check if pyproject.toml exists in current directory
+    if (cwd / "pyproject.toml").exists():
+        return None  # Project is in same directory as Makefile
+
+    # Search immediate subdirectories for pyproject.toml
+    for subdir in cwd.iterdir():
+        if subdir.is_dir() and (subdir / "pyproject.toml").exists():
+            return subdir.name
+
+    return None  # No Python project detected
 
 
 def init_command(args: argparse.Namespace):
@@ -286,12 +302,48 @@ def init_command(args: argparse.Namespace):
         with open(args.preseeds) as fd:
             preseeds = yaml.load(fd.read(), yaml.SafeLoader)
 
+    # Handle project-path-python from CLI or auto-detection
+    project_path_python = args.project_path_python
+    if project_path_python is None and not args.preseeds:
+        # Try auto-detection only if not using preseeds
+        detected_path = auto_detect_project_path_python()
+        if detected_path:
+            sys.stdout.write(
+                f"Auto-detected Python project in subdirectory: {detected_path}\n"
+            )
+            if prompt:
+                yn = inquirer.text(
+                    message=f"Use '{detected_path}' as PROJECT_PATH_PYTHON? (Y/n)"
+                )
+                if yn not in ["n", "N"]:
+                    project_path_python = detected_path
+            else:
+                project_path_python = detected_path
+
+    # Inject project-path-python into preseeds if specified or detected
+    if project_path_python:
+        if preseeds is None:
+            preseeds = {}
+        if "topics" not in preseeds:
+            preseeds["topics"] = {}
+        if "core" not in preseeds["topics"]:
+            preseeds["topics"]["core"] = {}
+        if "base" not in preseeds["topics"]["core"]:
+            preseeds["topics"]["core"]["base"] = {}
+        preseeds["topics"]["core"]["base"]["PROJECT_PATH_PYTHON"] = project_path_python
+        sys.stdout.write(f"Setting PROJECT_PATH_PYTHON={project_path_python}\n\n")
+
     create_config(prompt=prompt, preseeds=preseeds)
 
 
 init_parser = command_parsers.add_parser("init", help="Initialize project")
 init_parser.set_defaults(func=init_command)
 init_parser.add_argument("-p", "--preseeds", help="Preseeds file")
+init_parser.add_argument(
+    "--project-path-python",
+    help="Path to Python project relative to Makefile (for monorepo setups)",
+    default=None,
+)
 
 
 def update_command(args: argparse.Namespace):

src/mxmake/templates.py

@@ -265,7 +265,7 @@ def template_variables(self) -> dict[str, typing.Any]:
                         name=setting.name,
                         description=setting.description.split("\n"),
                         default=setting.default,
-                        value=self.domain_settings[sfqn],
+                        value=self.domain_settings.get(sfqn, setting.default),
                     )
                 )
         # render domain sections
@@ -333,10 +333,12 @@ def __init__(
         target_folder: Path,
         domains: list[Domain],
         environment: Environment | None = None,
+        settings: dict[str, str] | None = None,
     ) -> None:
         super().__init__(environment)
         self.target_folder = target_folder
         self.domains = domains
+        self.settings = settings or {}
 
     @property
     def template_variables(self) -> dict[str, typing.Any]:
@@ -359,7 +361,10 @@ def template_variables(self) -> dict[str, typing.Any]:
                     ),
                 )
                 mxmake_templates.append(template)
-        return dict(mxmake_templates=mxmake_templates, mxmake_env=mxmake_env)
+        return dict(
+            mxmake_templates=mxmake_templates,
+            mxmake_env=mxmake_env,
+        )
 
 
 ##############################################################################
@@ -442,7 +447,19 @@ def __call__(self, ob: type["Template"]) -> type["Template"]:
 
 
 class GHActionsTemplate(Template):
-    template_variables = dict()
+    def __init__(
+        self,
+        environment: Environment | None = None,
+        settings: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(environment)
+        self.settings = settings or {}
+
+    @property
+    def template_variables(self) -> dict[str, typing.Any]:
+        return dict(
+            project_path_python=self.settings.get("PROJECT_PATH_PYTHON", ""),
+        )
 
     @property
     def target_folder(self) -> Path:

src/mxmake/templates/gh-actions-lint.yml

@@ -13,7 +13,7 @@ jobs:
         uses: astral-sh/setup-uv@v5
         with:
           enable-cache: true
-          cache-dependency-glob: "pyproject.toml"
+          cache-dependency-glob: "{% if project_path_python %}{{ project_path_python }}/{% endif %}pyproject.toml"
 
       - name: Set up Python 3.10
         run: uv python install 3.10

src/mxmake/templates/gh-actions-test.yml

@@ -23,7 +23,7 @@ jobs:
       uses: astral-sh/setup-uv@v5
       with:
         enable-cache: true
-        cache-dependency-glob: "pyproject.toml"
+        cache-dependency-glob: "{% if project_path_python %}{{ project_path_python }}/{% endif %}pyproject.toml"
 
     - name: Set up Python {{ "${{ matrix.python }}" }}
       run: uv python install {{ "${{ matrix.python }}" }}