Migrate docs to Zensical, expand dev docs#357
Merged
Conversation
Normal deployment of the REST API is unaffected by ES. It is only when developers want to use it for migration tests that it matters.
Contributor
|
Warning Review limit reached
Next review available in: 43 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (9)
WalkthroughThis PR restructures project documentation and migrates the documentation build tooling from mkdocs-material to Zensical. Changes include a reorganized mkdocs.yml navigation, updated Dockerfiles and pyproject.toml extras, and new/rewritten documentation covering contributing guidelines, code of conduct, CI/CD, development setup, code architecture, database schema, project overview, migration guide, and a phased roadmap. Some previously existing docs (project overview, database index) had content removed. Pre-commit configuration was adjusted to handle Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
There was a problem hiding this comment.
Hey - I've found 5 issues, and left some high level feedback:
- There are a few spelling/typo issues in the new docs (e.g.,
Pyhon-based API,uv pip instal -e ".[dev]", missing space inThecodefield) that are worth correcting for clarity and polish. - The
!! tip "Can't connect to Docker?"block indocs/development/documentation.mdlikely won't render as an admonition with Zensical; consider changing it to a standard admonition syntax (e.g.,!!! tip) to match the rest of the docs. - In
docs/development/setup.mdthepyproject.tomllink is empty ([pyproject.toml]()); it would be helpful to point this to the actual file or remove the link if not needed.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- There are a few spelling/typo issues in the new docs (e.g., `Pyhon-based API`, `uv pip instal -e ".[dev]"`, missing space in `The`code` field`) that are worth correcting for clarity and polish.
- The `!! tip "Can't connect to Docker?"` block in `docs/development/documentation.md` likely won't render as an admonition with Zensical; consider changing it to a standard admonition syntax (e.g., `!!! tip`) to match the rest of the docs.
- In `docs/development/setup.md` the `pyproject.toml` link is empty (`[pyproject.toml]()`); it would be helpful to point this to the actual file or remove the link if not needed.
## Individual Comments
### Comment 1
<location path="docs/migration.md" line_range="20-22" />
<code_context>
-# RFC 9457 Errors
-Errors will follow the RFC9457 standard. However, the original "code" is preserved through a custom field.
+## Standardized Errors
+The Pyhon-based API will return different HTTP status codes depending on the error (for example, returning `404 NOT FOUND` if a requested dataset does not exist).
+Moreover, the body of the response will contain a JSON body that adheres to the RFC9457 standard.
+
</code_context>
<issue_to_address>
**issue (typo):** Correct the typo in "Pyhon-based API".
```suggestion
## Standardized Errors
The Python-based API will return different HTTP status codes depending on the error (for example, returning `404 NOT FOUND` if a requested dataset does not exist).
Moreover, the body of the response will contain a JSON body that adheres to the RFC9457 standard.
```
</issue_to_address>
### Comment 2
<location path="docs/roadmap.md" line_range="2" />
<code_context>
+The REST API is currently under development.
+It's does not yet have feature parity with the PHP-based REST API.
+We are currently working on Phase 1 and Phase 2 in parallel, and to deploy to production before the end of 2026.
+The sunset date of the PHP-based REST API will be depend on the progress of this reimplementation and that of some other required server services.
</code_context>
<issue_to_address>
**issue (typo):** Fix grammar in "It's does not yet have feature parity".
Please change this sentence to either "It does not yet have feature parity" or "It's not yet at feature parity" to fix the grammatical error.
```suggestion
It does not yet have feature parity with the PHP-based REST API.
```
</issue_to_address>
### Comment 3
<location path="docs/roadmap.md" line_range="4" />
<code_context>
+The REST API is currently under development.
+It's does not yet have feature parity with the PHP-based REST API.
+We are currently working on Phase 1 and Phase 2 in parallel, and to deploy to production before the end of 2026.
+The sunset date of the PHP-based REST API will be depend on the progress of this reimplementation and that of some other required server services.
+
+## Phase 1: Achieve Feature Parity
</code_context>
<issue_to_address>
**issue (typo):** Correct "will be depend on" to "will depend on".
This wording is ungrammatical; please update it as suggested in the summary.
```suggestion
The sunset date of the PHP-based REST API will depend on the progress of this reimplementation and that of some other required server services.
```
</issue_to_address>
### Comment 4
<location path="docs/roadmap.md" line_range="34" />
<code_context>
+
+
+## Other Services
+Besides the REST API, there are a few other components which need to be developed:
+
+ - A logstash pipeline to populate ES indices based on the database data and/or a message queue. Currently, the PHP-based REST API directly puts documents into ES indices, which makes it prone to getting out of sync, and requires an ES server to run to use/test the API in ways which otherwise to not require an ES index.
+ - Evaluation Engine. A service which computes meta-features for datasets, including the "qualities" and "features" you find with datasets.
</code_context>
<issue_to_address>
**suggestion (typo):** Tidy up grammar in the sentence about ES indices and usage.
The phrase "in ways which otherwise to not require an ES index" is grammatically incorrect. Please change it to "in ways which otherwise would not require an ES index".
```suggestion
- A logstash pipeline to populate ES indices based on the database data and/or a message queue. Currently, the PHP-based REST API directly puts documents into ES indices, which makes it prone to getting out of sync, and requires an ES server to run to use/test the API in ways which otherwise would not require an ES index.
```
</issue_to_address>
### Comment 5
<location path="docs/development/project_overview.md" line_range="15" />
<code_context>
+
+
+The REST API should always be deployed with access to a database.
+In production, these services are deployed in a kubernetes cluster.
+A typical request flow would then follow this pattern:
+
</code_context>
<issue_to_address>
**nitpick (typo):** Capitalize "Kubernetes".
Please capitalize "Kubernetes" here to match standard usage.
```suggestion
In production, these services are deployed in a Kubernetes cluster.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #357 +/- ##
=======================================
Coverage 94.56% 94.56%
=======================================
Files 77 77
Lines 3774 3774
Branches 247 247
=======================================
Hits 3569 3569
Misses 137 137
Partials 68 68 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Actionable comments posted: 10
🧹 Nitpick comments (3)
docker/docs/Dockerfile (1)
1-3: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winSpecify a non-root USER in the Dockerfile.
Trivy flags that the container runs as root (DS-0002). Since this Dockerfile is being modified for the Zensical migration, consider adding a
USERdirective to run as a non-root user. If thezensical/zensicalbase image provides a non-root user, reference it explicitly; otherwise create one.🔒 Suggested non-root USER directive
FROM zensical/zensical ENTRYPOINT ["zensical"] CMD ["serve", "--dev-addr=0.0.0.0:8000"] + +USER ${ZENSICAL_USER:-zensical}If the base image does not define a non-root user, create one explicitly:
FROM zensical/zensical + +RUN useradd --create-home --shell /bin/bash zensical +USER zensical + ENTRYPOINT ["zensical"] CMD ["serve", "--dev-addr=0.0.0.0:8000"]🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docker/docs/Dockerfile` around lines 1 - 3, The Dockerfile currently launches the container as root because it only sets FROM, ENTRYPOINT, and CMD; add a USER directive in this Dockerfile so the runtime uses a non-root account. Check whether the zensical/zensical base image already defines a suitable non-root user and reference it explicitly, otherwise create a dedicated user in the image before the ENTRYPOINT/CMD setup.Source: Linters/SAST tools
docs/development/code.md (1)
145-148: 📐 Maintainability & Code Quality | 🔵 TrivialFill or remove the empty SQLAlchemy section.
### SQLAlchemyis currently blank, so this reads like a missing section rather than intentional structure.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/development/code.md` around lines 145 - 148, The SQLAlchemy section in the documentation is empty, so either add the intended content under the “SQLAlchemy” heading or remove that heading entirely if it is not meant to exist. Update the nearby “ORM usage” section in the same docs file so the structure reads intentionally, and keep the heading hierarchy consistent with the rest of the document.docs/development/documentation.md (1)
1-13: 📐 Maintainability & Code Quality | 🔵 TrivialUpdate the page title to Zensical.
The page already describes Zensical, so keeping the old
mkdocs-materialheading makes it look stale.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/development/documentation.md` around lines 1 - 13, The page heading still says “Documentation with mkdocs-material” even though the content is about Zensical, so update the top-level title in the documentation page to match Zensical. Use the existing documentation page content as the source of truth and adjust the main heading near the start of the file so the page title aligns with the referenced framework.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/contributing/index.md`:
- Around line 45-53: The “Help Wanted” restriction in the contributing guide is
too broad and reads as if it blocks all community contributions, which conflicts
with the earlier docs exception. Update the wording in the contributing docs
section so it applies only to code contributions, or add an explicit exemption
for documentation fixes, keeping the restriction aligned with the existing
minor-docs allowance.
- Around line 30-31: The link in the contributing docs points to the project
overview instead of the documentation workflow page. Update the reference in the
text near the “Developer Documentation” link so it targets the documentation
contribution page (the one currently using project_overview.md) and make sure
the surrounding wording still matches the docs workflow guidance.
In `@docs/development/documentation.md`:
- Around line 45-47: The admonition in the documentation is using an invalid
MkDocs marker, so it will not render as a tip. Update the existing tip block in
the documentation to use the proper MkDocs admonition syntax with the valid tip
marker, and keep the content under that block unchanged; this is the section
that starts with the “Can’t connect to Docker?” tip.
- Around line 35-39: The documentation example uses the module invocation form
instead of the CLI entrypoint; update the build-and-serve instructions in
documentation.md to use the same zensical serve command as the package
entrypoint and docker/docs/Dockerfile. Locate the command block in the docs
section and replace the python -m invocation with the CLI form so the documented
usage matches the actual runtime entrypoint.
In `@docs/development/setup.md`:
- Around line 21-26: The setup snippet in docs/development/setup.md has two
issues: the pyproject.toml reference is missing its target, and the uv install
command misspells install. Update the documentation around the dependency
installation example so the pyproject.toml link points to the actual file, and
correct the uv command in the same snippet to use the proper uv pip install
invocation while keeping the existing ".[dev]" extra. Use the surrounding setup
example to locate the markdown block.
In `@docs/index.md`:
- Around line 7-20: The heading structure in the docs page skips a level, which
breaks the outline. Update the section headings under the page title in the
markdown content so they use a consistent hierarchy, either by promoting the
current ### sections to ## or by inserting an intermediate ## section before
them. Keep the existing section titles in place and ensure the structure in
docs/index.md remains sequential.
In `@docs/installation.md`:
- Around line 9-12: The Swagger Docs URL is currently presented as if it is
always available on localhost:8001, but that only applies when the
port-published compose setup is used. Update the installation instructions in
the docs so the Swagger URL appears only under the branch that uses
compose.ports.yaml, or explicitly state that http://localhost:8001/docs is
reachable only after publishing the port with the port overlay. Use the
surrounding install steps and the REST API/Swagger docs text to keep the scope
clear.
In `@docs/migration.md`:
- Around line 39-47: Clarify the RFC 9457 field contract in the migration docs:
the `type` field should be described as the problem URI, not the legacy numeric
error code. Update the wording in this section to state that
`src/core/errors.py` still emits the numeric identifier separately in `code`,
and that clients should use `type` to identify the problem while treating `code`
as deprecated migration support.
In `@docs/roadmap.md`:
- Around line 1-4: Tighten the opening paragraph in the roadmap copy by fixing
the two grammar issues: change the phrasing in the introductory text so “It’s
does not yet” becomes a correct sentence, and update the sentence about the
PHP-based REST API sunset so “will be depend” is corrected. Keep the same
meaning while cleaning the wording in the paragraph content.
In `@mkdocs.yml`:
- Around line 18-40: The nested Development navigation label is duplicated,
causing redundant breadcrumbs; update the inner Development section in mkdocs
nav to a distinct name like Guides or Workflow. Adjust the nav entry that groups
Getting Started, Writing Code, Writing Tests, CI/CD, and Documentation so the
top-level Development item remains unchanged while the nested group uses a
unique label.
---
Nitpick comments:
In `@docker/docs/Dockerfile`:
- Around line 1-3: The Dockerfile currently launches the container as root
because it only sets FROM, ENTRYPOINT, and CMD; add a USER directive in this
Dockerfile so the runtime uses a non-root account. Check whether the
zensical/zensical base image already defines a suitable non-root user and
reference it explicitly, otherwise create a dedicated user in the image before
the ENTRYPOINT/CMD setup.
In `@docs/development/code.md`:
- Around line 145-148: The SQLAlchemy section in the documentation is empty, so
either add the intended content under the “SQLAlchemy” heading or remove that
heading entirely if it is not meant to exist. Update the nearby “ORM usage”
section in the same docs file so the structure reads intentionally, and keep the
heading hierarchy consistent with the rest of the document.
In `@docs/development/documentation.md`:
- Around line 1-13: The page heading still says “Documentation with
mkdocs-material” even though the content is about Zensical, so update the
top-level title in the documentation page to match Zensical. Use the existing
documentation page content as the source of truth and adjust the main heading
near the start of the file so the page title aligns with the referenced
framework.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 37f4ca06-3cd5-45c2-a00d-1f853553d33d
📒 Files selected for processing (22)
.pre-commit-config.yamldocker/docs/Dockerfiledocker/python/Dockerfiledocs/contributing/code_of_conduct.mddocs/contributing/index.mddocs/contributing/project_overview.mddocs/database/index.mddocs/development/CI_CD.mddocs/development/code.mddocs/development/database/index.mddocs/development/database/openml.mddocs/development/database/openml_expdb.mddocs/development/documentation.mddocs/development/project_overview.mddocs/development/setup.mddocs/development/tests.mddocs/index.mddocs/installation.mddocs/migration.mddocs/roadmap.mdmkdocs.ymlpyproject.toml
💤 Files with no reviewable changes (2)
- docs/database/index.md
- docs/contributing/project_overview.md
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Switch to Zensical from mkdocs because mkdocs 1.x is not maintained and mkdocs 2.0 will not be compatible with mkdocs material.
Also expanded the documentation pages significantly.