zmerge 0.1.0__tar.gz

zmerge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Markus Bilz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

zmerge-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: zmerge
+Version: 0.1.0
+Summary: Merge the documentation of multiple Zensical projects into one site with working links and a global search 📚.
+Keywords: documentation,monorepo,zensical,mkdocs
+Author: Markus Bilz
+Author-email: Markus Bilz <github@markusbilz.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli-w>=1.2
+Requires-Dist: zensical>=0.0.39
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/KarelZe/zmerge
+Project-URL: Documentation, https://karelze.github.io/zmerge/
+Project-URL: Bug Tracker, https://github.com/KarelZe/zmerge/issues
+Description-Content-Type: text/markdown
+
+# zmerge 📚
+
+[![PyPI](https://img.shields.io/pypi/v/zmerge)](https://pypi.org/project/zmerge/)
+[![Test](https://github.com/KarelZe/zmerge/actions/workflows/test.yml/badge.svg)](https://github.com/KarelZe/zmerge/actions/workflows/test.yml)
+[![Docs](https://img.shields.io/badge/docs-zensical-blue)](https://karelze.github.io/zmerge/)
+
+`zmerge` merges the documentation of multiple [Zensical](https://zensical.org/) projects into one site with working
+links, a single navigation and one global search. It fills the gap left by the
+[mkdocs-monorepo-plugin](https://github.com/backstage/mkdocs-monorepo-plugin) until Zensical ships
+[an official solution](https://github.com/zensical/backlog/issues/22).
+
+- **No custom Zensical, no plugins.** zmerge assembles one regular Zensical project and builds it with `zensical build`.
+- **One site.** One navigation, one global search, one link check across all projects.
+- **Links that work everywhere.** Links between projects use the projects' published URLs and are rewritten into
+  validated relative links when merging.
+- **Per-project settings.** Markdown extensions, plugins, mkdocstrings options and snippets of every project are merged.
+- **Local or git.** Include projects from local paths or straight from git repositories.
+- **Fast.** Hardlinks instead of copies, incremental re-assembly in a few milliseconds, and `zmerge serve` for live
+  previews.
+
+## Installation
+
+```bash
+uv tool install zmerge --with mkdocstrings-python  # mkdocstrings-python only if you render API docs
+```
+
+## Quick start
+
+Include other projects in the `nav` of an umbrella project's `zensical.toml`, just like with the
+mkdocs-monorepo-plugin:
+
+```toml
+[project]
+site_name = "My projects"
+site_url = "https://example.github.io/"
+nav = [
+  { Home = "index.md" },
+  { lev = "!include ../lev/zensical.toml" },
+  { dame = "!include git+https://github.com/KarelZe/dame-rs.git" },
+]
+```
+
+Then build or preview the merged site:
+
+```bash
+zmerge build --strict
+zmerge serve
+```
+
+Add `.zmerge/` and `.zmerge.toml` to your `.gitignore`. See the [documentation](https://karelze.github.io/zmerge/) for
+the configuration, linking between projects and [limitations](https://karelze.github.io/zmerge/limitations/), and
+[examples/karelze](examples/karelze) for a complete umbrella site.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run prek run --all-files
+uv run zensical serve
+```
+
+> [!WARNING]
+> zmerge is not affiliated with the Zensical project. It is purely meant as a temporary solution until Zensical ships
+> official support for merging projects, tracked in [zensical/backlog#22](https://github.com/zensical/backlog/issues/22).

zmerge-0.1.0/README.md

@@ -0,0 +1,65 @@
+# zmerge 📚
+
+[![PyPI](https://img.shields.io/pypi/v/zmerge)](https://pypi.org/project/zmerge/)
+[![Test](https://github.com/KarelZe/zmerge/actions/workflows/test.yml/badge.svg)](https://github.com/KarelZe/zmerge/actions/workflows/test.yml)
+[![Docs](https://img.shields.io/badge/docs-zensical-blue)](https://karelze.github.io/zmerge/)
+
+`zmerge` merges the documentation of multiple [Zensical](https://zensical.org/) projects into one site with working
+links, a single navigation and one global search. It fills the gap left by the
+[mkdocs-monorepo-plugin](https://github.com/backstage/mkdocs-monorepo-plugin) until Zensical ships
+[an official solution](https://github.com/zensical/backlog/issues/22).
+
+- **No custom Zensical, no plugins.** zmerge assembles one regular Zensical project and builds it with `zensical build`.
+- **One site.** One navigation, one global search, one link check across all projects.
+- **Links that work everywhere.** Links between projects use the projects' published URLs and are rewritten into
+  validated relative links when merging.
+- **Per-project settings.** Markdown extensions, plugins, mkdocstrings options and snippets of every project are merged.
+- **Local or git.** Include projects from local paths or straight from git repositories.
+- **Fast.** Hardlinks instead of copies, incremental re-assembly in a few milliseconds, and `zmerge serve` for live
+  previews.
+
+## Installation
+
+```bash
+uv tool install zmerge --with mkdocstrings-python  # mkdocstrings-python only if you render API docs
+```
+
+## Quick start
+
+Include other projects in the `nav` of an umbrella project's `zensical.toml`, just like with the
+mkdocs-monorepo-plugin:
+
+```toml
+[project]
+site_name = "My projects"
+site_url = "https://example.github.io/"
+nav = [
+  { Home = "index.md" },
+  { lev = "!include ../lev/zensical.toml" },
+  { dame = "!include git+https://github.com/KarelZe/dame-rs.git" },
+]
+```
+
+Then build or preview the merged site:
+
+```bash
+zmerge build --strict
+zmerge serve
+```
+
+Add `.zmerge/` and `.zmerge.toml` to your `.gitignore`. See the [documentation](https://karelze.github.io/zmerge/) for
+the configuration, linking between projects and [limitations](https://karelze.github.io/zmerge/limitations/), and
+[examples/karelze](examples/karelze) for a complete umbrella site.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run prek run --all-files
+uv run zensical serve
+```
+
+> [!WARNING]
+> zmerge is not affiliated with the Zensical project. It is purely meant as a temporary solution until Zensical ships
+> official support for merging projects, tracked in [zensical/backlog#22](https://github.com/zensical/backlog/issues/22).

zmerge-0.1.0/pyproject.toml

@@ -0,0 +1,147 @@
+[build-system]
+requires = ["uv_build>=0.12.0,<0.14.0"]
+build-backend = "uv_build"
+
+[project]
+name = "zmerge"
+version = "0.1.0"
+description = "Merge the documentation of multiple Zensical projects into one site with working links and a global search 📚."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "documentation",
+    "monorepo",
+    "zensical",
+    "mkdocs",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Developers",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Documentation",
+]
+dependencies = [
+    "pyyaml>=6.0",
+    "tomli-w>=1.2",
+    "zensical>=0.0.39",
+]
+
+[[project.authors]]
+name = "Markus Bilz"
+email = "github@markusbilz.com"
+
+[project.scripts]
+zmerge = "zmerge.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/KarelZe/zmerge"
+Documentation = "https://karelze.github.io/zmerge/"
+"Bug Tracker" = "https://github.com/KarelZe/zmerge/issues"
+
+[dependency-groups]
+test = [
+    "mkdocstrings-python",
+    "pytest",
+    "pytest-cov",
+]
+docs = ["zensical"]
+dev = [
+    { include-group = "test" },
+    { include-group = "docs" },
+    "prek>=0.5",
+    "ruff",
+    "ty",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra -p no:warnings -v --cov --cov-report term-missing --doctest-modules"
+testpaths = [
+    "tests",
+    "src",
+]
+
+[tool.coverage.run]
+source = ["zmerge"]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+show_missing = true
+
+[tool.ty.rules]
+unresolved-import = "error"
+unused-ignore-comment = "warn"
+possibly-unresolved-reference = "error"
+redundant-cast = "error"
+deprecated = "error"
+
+[tool.uv]
+exclude-newer = "7 days"
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "C4",
+    "D",
+    "DOC",
+    "E",
+    "F",
+    "FURB",
+    "I",
+    "N",
+    "PT",
+    "PTH",
+    "RET",
+    "RUF",
+    "SIM",
+    "TC",
+    "TD",
+    "TID",
+    "UP",
+    "W",
+]
+ignore = [
+    "D203",
+    "D212",
+    "DOC502",
+    "E501",
+]
+preview = true
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.pydoclint]
+ignore-one-line-docstrings = true
+
+[tool.ruff.lint.isort]
+known-first-party = ["zmerge"]
+section-order = [
+    "future",
+    "standard-library",
+    "third-party",
+    "first-party",
+    "local-folder",
+]
+
+[tool.ruff.format]
+preview = true

zmerge-0.1.0/pyproject.toml.orig

@@ -0,0 +1,127 @@
+[build-system]
+requires = ["uv_build>=0.12.0,<0.14.0"]
+build-backend = "uv_build"
+
+[project]
+name = "zmerge"
+version = "0.1.0"
+authors = [{ name = "Markus Bilz", email = "github@markusbilz.com" }]
+description = "Merge the documentation of multiple Zensical projects into one site with working links and a global search 📚."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = ["documentation", "monorepo", "zensical", "mkdocs"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Topic :: Documentation",
+  "Topic :: Software Development :: Documentation",
+]
+
+dependencies = ["pyyaml>=6.0", "tomli-w>=1.2", "zensical>=0.0.39"]
+
+[project.scripts]
+zmerge = "zmerge.cli:main"
+
+[project.urls]
+"Homepage" = "https://github.com/KarelZe/zmerge"
+"Documentation" = "https://karelze.github.io/zmerge/"
+"Bug Tracker" = "https://github.com/KarelZe/zmerge/issues"
+
+[dependency-groups]
+test = ["mkdocstrings-python", "pytest", "pytest-cov"]
+docs = ["zensical"]
+dev = [
+  { include-group = "test" },
+  { include-group = "docs" },
+  "prek>=0.5",
+  "ruff",
+  "ty",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra -p no:warnings -v --cov --cov-report term-missing --doctest-modules"
+testpaths = ["tests", "src"]
+
+[tool.coverage.run]
+source = ["zmerge"]
+branch = true
+
+[tool.coverage.report]
+exclude_also = ["if __name__ == .__main__.:", "if TYPE_CHECKING:"]
+show_missing = true
+
+[tool.ty.rules]
+unresolved-import = "error"
+unused-ignore-comment = "warn"
+possibly-unresolved-reference = "error"
+redundant-cast = "error"
+deprecated = "error"
+
+[tool.uv]
+exclude-newer = "7 days"
+
+[tool.ruff]
+
+line-length = 120
+
+[tool.ruff.lint]
+
+# See rules: https://beta.ruff.rs/docs/rules/
+select = [
+  "A",    # shadow builtins
+  "C4",   # Catch incorrect use of comprehensions, dict, list, etc
+  "D",    # pydocstyle
+  "DOC",  # pydoclint
+  "E",    # PyCodeStyle errors
+  "F",    # Pyflakes rules
+  "FURB", # refurb
+  "I",    # isort
+  "N",    # enforce naming conventions, e.g. ClassName vs function_name
+  "PT",   # pytest
+  "PTH",  # flake8-use-pathlib
+  "RET",  # Good return practices
+  "RUF",  # ruff-specific rules
+  "SIM",  # Common simplification rules
+  "TC",   # Enforce importing certain types in a TYPE_CHECKING block
+  "TD",   # Be diligent with TODO comments
+  "TID",  # Some good import practices
+  "UP",   # Warn if certain things can changed due to newer Python versions
+  "W",    # PyCodeStyle warnings
+]
+
+ignore = ["D203", "D212", "DOC502", "E501"]
+
+preview = true
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.pydoclint]
+# Short helpers document their behaviour in one line.
+ignore-one-line-docstrings = true
+
+[tool.ruff.lint.isort]
+known-first-party = ["zmerge"]
+section-order = [
+  "future",
+  "standard-library",
+  "third-party",
+  "first-party",
+  "local-folder",
+]
+
+[tool.ruff.format]
+preview = true

zmerge-0.1.0/src/zmerge/__init__.py

@@ -0,0 +1,7 @@
+"""Merge the documentation of multiple Zensical projects into one site."""
+
+from importlib.metadata import version
+
+__version__ = version("zmerge")
+
+__all__ = ["__version__"]

zmerge-0.1.0/src/zmerge/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m zmerge``."""
+
+import sys
+
+from zmerge.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())