Refactor docs. Migrate form deprecated mkdocs to zensical

[SommerKai]

This pull request migrates the documentation system from MkDocs to Zensical, reorganizes documentation files, and updates related tooling and configuration throughout the repository. The changes ensure all references, scripts, and workflows point to the new docs/ directory and Zensical configuration, removing MkDocs-specific files and settings.

Documentation system migration and reorganization:

• Migrated documentation from mkdocs/ to the top-level docs/ directory, updating all references in scripts, configuration files, and documentation to use the new location. MkDocs configuration and directory are removed, and a new zensical.toml config is introduced at the repo root. ([[1]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-c785042929d7b216744f869cd6ace6657b73aaf6a5f041da1d096c2b6e34ff04R1-R57), [[2]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-9e9229c1e192de639c58ee7f515c8feed844a6571b08deffc39c317be31d05a7L1-L77), [[3]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-6d015afd5ea56e5576b919e19ae25efc518025f2e139e5b3b29a6b1bb79b2218L58-R58), [[4]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-6d015afd5ea56e5576b919e19ae25efc518025f2e139e5b3b29a6b1bb79b2218L262-R262), [[5]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-6d015afd5ea56e5576b919e19ae25efc518025f2e139e5b3b29a6b1bb79b2218L272-R272), [[6]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-b4d68dc855d0f9476d3f2ee343853bd21bf82ea9960d0cf06661baa244439dd6R1), [[7]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-d7711df238953b4a8cb6a9bd6bd8a18264b44d09ad43d0aa4fd56f7c278867b6L1))
• Updated documentation build and serve commands to use Zensical instead of MkDocs in pyproject.toml, CLAUDE.md, and pre-commit hooks. ([[1]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-50c86b7ed8ac2cf95bd48334961bf0530cdc77b5a56f852c5c61b89d735fd711L338-R333), [[2]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-50c86b7ed8ac2cf95bd48334961bf0530cdc77b5a56f852c5c61b89d735fd711L347-R342), [[3]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-6ebdb617a8104a7756d0cf36578ab01103dc9f07e4dc6feb751296b9c402faf7L23-R23), [[4]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-63a9c44a44acf85fea213a857769990937107cf072831e1a26808cfde9d096b9L74-R74))

Workflow and automation updates:

• Updated GitHub Actions workflows to build and deploy documentation using Zensical and the new docs/ structure, renaming jobs and updating artifact paths accordingly. ([[1]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-126bf89616b7daa3d14ebc882ad18666aaf1c3dae888c4ba306a66ec80758bc1L226-R227), [[2]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-126bf89616b7daa3d14ebc882ad18666aaf1c3dae888c4ba306a66ec80758bc1L253-R262))

Tooling and script adjustments:

• Updated the docs code fence checker script and related documentation to scan the new docs/ directory instead of mkdocs/docs/. ([[1]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-c77911b714dff270a83f2ff927f6cf794b0a546303dd8f5e87aa51de7d620000L4-R4), [[2]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-c77911b714dff270a83f2ff927f6cf794b0a546303dd8f5e87aa51de7d620000L94-R95))
• Updated the pre-commit configuration to lint and check only relevant directories, removing docs/ from exclusion and updating hooks to target the new path. ([[1]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-63a9c44a44acf85fea213a857769990937107cf072831e1a26808cfde9d096b9L2-R2), [[2]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-63a9c44a44acf85fea213a857769990937107cf072831e1a26808cfde9d096b9L74-R74))

Dependency and changelog configuration:

• Replaced MkDocs and related plugins with Zensical in the docs dependency group in pyproject.toml, and updated changelog file paths to docs/Changelog.md throughout configuration and documentation. ([[1]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-50c86b7ed8ac2cf95bd48334961bf0530cdc77b5a56f852c5c61b89d735fd711L99-L106), [[2]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-50c86b7ed8ac2cf95bd48334961bf0530cdc77b5a56f852c5c61b89d735fd711L273-R268), [[3]](https://github.com/Bayer-Group/MotherML/pull/72/files#diff-9fbf0b053168173524e7b36c20eb53181ba6fcd5ab3152a516511ac2520d9bfcL29-R36))

These changes collectively modernize and streamline the documentation workflow, making it easier to maintain and build project docs using Zensical.

[Copilot]

Pull request overview

This PR migrates the project documentation stack from MkDocs (under mkdocs/) to Zensical (top-level docs/ + zensical.toml), and updates automation/tooling to build, validate, and deploy the docs from the new layout.

Changes:

• Introduces zensical.toml and replaces MkDocs build/serve usage with zensical across tooling and CI.
• Moves/rebuilds documentation content under docs/ and updates references/paths accordingly.
• Updates pre-commit hooks and workflows to validate docs and publish the new site/ output.

Reviewed changes

Copilot reviewed 11 out of 22 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
zensical.toml	New Zensical site configuration (nav/theme/plugins).
uv.lock	Updates lockfile to reflect docs toolchain dependency changes.
scripts/check_docs_python_fences.py	Switches docs fence scanning default root to docs/.
pyproject.toml	Replaces MkDocs deps/tasks with Zensical equivalents; updates changelog path.
mkdocs/mkdocs.yml	Removes MkDocs configuration (migration away from MkDocs).
docs/standardization.md	Adds standardization docs page under new docs root.
docs/mother/overview.md	Adds “Mother framework” overview page under docs/.
docs/mother/models.md	Adds models documentation and API/doc integration examples.
docs/mother/configurator.md	Adds settings/configurator docs and embedded config examples.
docs/feature_generation.md	Adds feature generation documentation under docs/.
docs/examples.md	Adds tutorial index linking to example notebooks.
docs/development/pr_approval_guidelines.md	Adds PR approval guideline doc page in new structure.
docs/development/dev.md	Updates dev docs to reference Zensical + new changelog path.
docs/chemistry.md	Adds introductory chemistry guide and cross-links to other docs.
docs/Changelog.md	Adds changelog file in new authoritative docs location.
CLAUDE.md	Updates docs commands description to reflect Zensical.
.pre-commit-config.yaml	Adjusts exclusions and retargets docs fence hook to docs/.
.gitignore	Updates ignored build output to site/ (Zensical output).
.github/workflows/workflow.yml	Updates CI build/deploy jobs to build Zensical docs and publish site/.
.github/skills/update-docs/SKILL.md	Updates internal skill doc to reference new changelog/docs paths.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 22 changed files in this pull request and generated 1 comment.

[SommerKai]

there exists a symlink to index.md and it works

[thomasATbayer]

There are some suggestions from copilot still open, maybe have a look.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 22 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 23 changed files in this pull request and generated no new comments.

[thomasATbayer]

@SommerKai

for the failing tabpfn embedding which works in the

The difference between branches:

refactor_docs_KS (failing) → uv.lock was updated with newer dependencies, including aiohttp 3.14.3
main → Uses older dependencies in uv.lock, including aiohttp 3.14.2
Root Cause:

The uv.lock update on the refactor_docs_KS branch likely pulled in a newer version of PyTorch or another dependency that now uses BFloat16 by default in certain operations. The TabPFN model doesn't support BFloat16 tensors.

Solution
Add explicit float32 conversion in the TabPFNEmbeddingTransformer.fit() and fit_transform() methods to ensure input data is always float32 before being passed to TabPFN models:

Python
def fit(
self,
X: Union[np.ndarray, pd.DataFrame],
y: Optional[Union[np.ndarray, pd.Series]] = None,
groups: Optional[Union[np.ndarray, pd.Series]] = None,
only_best_embeddings: bool = False,
):
"""..."""
# Store feature names if input is DataFrame
is_dataframe: bool = isinstance(X, pd.DataFrame)
self.train_index_ = X.index if is_dataframe else None

if is_dataframe:
    self.input_features_ = X.columns.tolist()
    X_array: np.ndarray = X.values.astype(np.float32)  # ADD THIS LINE
else:
    self.input_features_ = None
    X_array: np.ndarray = np.asarray(X, dtype=np.float32)  # CONVERT HERE

if y is None:
    raise ValueError("TabPFN requires target values for fitting when no prefitted_model is provided.")

# Convert y to numpy array if it's a pandas Series
y_array: np.ndarray = y.values.astype(np.float32) if isinstance(y, pd.Series) else np.asarray(y, dtype=np.float32)  # ADD CONVERSION

# Rest of the method...

Additionally, update the transform() method:

Python
def transform(self, X: pd.DataFrame, only_best_embeddings: bool = False) -> pd.DataFrame:
"""..."""
if self.model is None:
raise ValueError("Transformer hasn't been fitted. Call 'fit' first or provide a pre-fitted model.")

index = X.index
if self.input_features_ is not None:
    if not all(feature in X.columns for feature in self.input_features_):
        missing_features: set = set(self.input_features_) - set(X.columns)
        raise ValueError(f"Features {missing_features} used for training are missing")
    X_array: np.ndarray = X[self.input_features_].values.astype(np.float32)  # ADD CONVERSION
else:
    X_array: np.ndarray = np.asarray(X, dtype=np.float32)  # CONVERT HERE

# Rest of the method...

This ensures that all data passed to TabPFN models is consistently float32, preventing the BFloat16 compatibility issue.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 26 changed files in this pull request and generated 7 comments.

Suppressed comments (3)

release-preflight-report.md:4

• This is a generated report produced by scripts/release_preflight.py and overwritten in each workflow workspace, but it is committed as a snapshot containing the current v1.0.6 commit range. The tracked copy will become stale after the next commit and is not what CI uses; keep it as an ignored artifact (or remove it from version control) instead of publishing misleading release data.

# Release Preflight Report

Base tag: v1.0.6
Commit count: 6

scripts/release_preflight.py:71

• This new release gate contains the commit parser, report generation, and strict exit behavior, but there are no unit tests for scripts/release_preflight.py. A small change to the regex, tag handling, or strict path can silently block releases; add focused tests for scoped/breaking commits, unsupported subjects, empty ranges, and strict/non-strict exits.

def classify(commit: Commit) -> str | None:
    match = CONVENTIONAL_RE.match(commit.subject)
    if not match:
        return None
    commit_type = match.group("type")
    if commit_type not in ALLOWED_TYPES:
        return None
    return commit_type

scripts/release_preflight.py:32

• revert is accepted by this allowlist, but semantic-release's explicit allowed_tags/other_allowed_tags in pyproject.toml omit it. A revert: commit can therefore pass this strict preflight and still be rejected or ignored by the release parser. Keep this allowlist in sync with semantic-release, or add revert to that configuration.

    "revert",

[thomasATbayer]

@SommerKai for @4xel-C tabicl PR we made sure that tabpfn only receives float so for this the tests run through, also would agree with Copilot that local adaption woulds be less intrusive: ca45d17

[Copilot]

Pull request overview

Copilot reviewed 15 out of 24 changed files in this pull request and generated 1 comment.

Suppressed comments (4)

.github/workflows/workflow.yml:308

• On a workflow_dispatch run on main, release can still produce a release, but test-pypi-publish is gated to github.event_name == 'push'. Since this job is now a required dependency and this condition also requires its result to be success, manual releases always skip publish-pypi. Allow the test-PyPI job for manual releases or make this dependency conditional for that event.

    needs: [release, test-pypi-publish]
    if: needs.release.outputs.released == 'true' && needs.test-pypi-publish.result == 'success'

scripts/release_preflight.py:96

• The report is titled "Commits missing issue or PR reference", but this check only searches commit.subject. A normal reference such as Fixes #123 in the commit body is therefore falsely reported as missing. Parse the full commit message when collecting issue references, or explicitly make the report subject-only.

        if not ISSUE_RE.search(commit.subject):

scripts/release_preflight.py:50

• On a push to main, actions/checkout updates origin/main to the same commit checked out as HEAD, so the default origin/main..HEAD range is empty. The main-branch run therefore reports zero commits and never validates the commits about to be released. Use the previous push SHA/release tag as the baseline for main runs, while retaining origin/main for pull requests.

def resolve_base_ref(base_ref: str) -> str:
    candidates = (f"origin/{base_ref}", base_ref) if base_ref == "main" else (base_ref,)

scripts/release_preflight.py:94

• This new release gate has no unit tests for classify, base-ref resolution, report generation, or strict exit handling. Those branches decide whether CI blocks a release, so add focused tests under test/unit/ before relying on this script.

    for commit in commits:
        commit_type = classify(commit)
        if commit_type is None:
            unknown.append(commit)
        else:
            categorized[commit_type].append(commit)

[github-actions]

Release Preflight

Automated check that complements semantic-release changelog generation.

# Release Preflight Report

Base ref: origin/main
Commit count: 9

## Conventional commit summary

- chore: 1
- docs: 4
- feat: 1
- fix: 3

## Commits missing issue or PR reference

- c0a90406 fix: Remove changelog file reference from semantic release configuration
- 44e39758 fix: Update release preflight script to validate commits against the main branch and remove outdated report file
- 0b4168c1 feat: Add release preflight workflow and reporting script
- 4ca0b255 docs: Add changelog file configuration to pyproject.toml
- 5313e073 docs: Update README to include 'Why Mother?" section
- 637ef56e docs: Add markdown extensions and update mkdocstrings configuration
- 16da4ab6 fix: Potential fix for pull request finding
- f6c168c7 chore: uv audit
- 508e3855 docs: Add initial configuration for Zensical documentation site

## Suggested manual follow-up

- Run the update-docs skill before release for issue and milestone reconciliation.
- Confirm docs updates for release-specific changes.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 24 changed files in this pull request and generated 4 comments.

Suppressed comments (4)

.github/workflows/workflow.yml:163

• On a push to main, actions/checkout updates origin/main to the pushed commit, so the script's default main base resolves to the same commit as HEAD and main..HEAD is empty. The preflight therefore never validates the commits that semantic-release will process on main. Select the prior release tag/previous SHA for main runs while retaining the base branch for PRs.

          python3 scripts/release_preflight.py --strict --output release-preflight-report.md

.github/workflows/workflow.yml:152

• This job runs for pull_request, checks out the PR merge ref, and then executes repository-controlled code while granting pull-requests: write and issues: write. A PR can modify the workflow or scripts/release_preflight.py and use that token to mutate issues/comments or exfiltrate credentials. Keep the untrusted preflight job read-only, and move the bot-comment operation to a separate trusted job/workflow that does not execute PR-controlled code.

    permissions:
      contents: read
      pull-requests: write
      issues: write

docs/development/dev.md:282

• The workflow only runs the comment step when github.event.pull_request.head.repo.full_name == github.repository, so pull requests from forks receive no sticky bot comment. Qualify this statement to same-repository PRs or document the artifact-only behavior for fork PRs.
  scripts/release_preflight.py:86
• The new release-preflight helper contains the base-ref resolution, commit classification, report generation, and strict-exit behavior, but no tests exercise it while this repository has an automated unit-test and coverage suite. Add unit tests for PR versus main base refs, unsupported subjects, empty ranges, and strict mode so release CI cannot silently stop auditing commits.

def build_report(base_ref: str, commits: list[Commit]) -> tuple[str, int]:
    categorized: dict[str, list[Commit]] = defaultdict(list)
    unknown: list[Commit] = []