Skip to content

Migrate from MkDocs to ProperDocs#3346

Merged
arkid15r merged 4 commits into
vacanza:devfrom
PPsyrius:properdocs_migration
Mar 21, 2026
Merged

Migrate from MkDocs to ProperDocs#3346
arkid15r merged 4 commits into
vacanza:devfrom
PPsyrius:properdocs_migration

Conversation

@PPsyrius

@PPsyrius PPsyrius commented Mar 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Proposed change

The migration is largely drop-in due to existing plugin compatibility with ProperDocs, with the exception that the ReadTheDocs theme now needs to be installed separately since came with no built-in theme.
image

Resolves #3345 .

Type of change

  • New country/market holidays support (thank you!)
  • Supported country/market holidays update (calendar discrepancy fix, localization)
  • Existing code/documentation/test/process quality improvement (best practice, cleanup, refactoring, optimization)
  • Dependency update (version deprecation/pin/upgrade)
  • Bugfix (non-breaking change which fixes an issue)
  • Breaking change (a code change causing existing functionality to break)
  • New feature (new holidays functionality in general)

Checklist

@coderabbitai

coderabbitai Bot commented Mar 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: bf48df21-573c-4d5c-8249-73dfe3dcee38

📥 Commits

Reviewing files that changed from the base of the PR and between 0460357 and 882ba37.

📒 Files selected for processing (5)
  • .properdocs.yml
  • .readthedocs.yaml
  • CONTRIBUTING.md
  • Makefile
  • make.cmd

Summary by CodeRabbit

  • Chores
    • Migrated documentation build system from MkDocs to ProperDocs.
    • Updated build configuration and project dependencies for the new documentation tooling.

Walkthrough

The PR replaces MkDocs with ProperDocs for building documentation by updating build commands, configuration references, dependency entries, and contributing documentation across repository files.

Changes

Cohort / File(s) Summary
ReadTheDocs config & build targets
.readthedocs.yaml, Makefile, make.cmd		 Switched build invocation and configuration reference from mkdocs/mkdocs.yml to properdocs/.properdocs.yml (commands now call properdocs build -f .properdocs.yml).
Contribution docs
CONTRIBUTING.md		 Reworded header and guidance to reference ProperDocs instead of MkDocs and updated linked primer and explanatory text.
Project dependencies
pyproject.toml		 Replaced mkdocs>=1.6.1,<2 with properdocs>=1.6.6,<2 and added properdocs-theme-readthedocs>=1.6.5,<2 in the docs dependency group.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main change: migrating documentation tooling from MkDocs to ProperDocs, which aligns with all file modifications.
Description check ✅ Passed The description is directly related to the changeset, explaining the migration rationale and noting plugin compatibility while acknowledging the separate theme requirement.
Linked Issues check ✅ Passed The PR fulfills all coding objectives from #3345: replacing mkdocs with properdocs in build commands, configuration files, and dependencies while maintaining plugin compatibility.
Out of Scope Changes check ✅ Passed All changes are scoped to the migration objectives—configuration, build scripts, and documentation references remain aligned with #3345's requirements.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@PPsyrius PPsyrius requested review from KJhellico and arkid15r and removed request for KJhellico March 19, 2026 04:44
@PPsyrius PPsyrius added the doc label Mar 19, 2026
@codecov

codecov Bot commented Mar 19, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (2b97bad) to head (882ba37).
⚠️ Report is 5 commits behind head on dev.

Additional details and impacted files 
@@            Coverage Diff            @@
##               dev     #3346   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          310       310           
  Lines        18578     18578           
  Branches      2379      2379           
=========================================
  Hits         18578     18578

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

coderabbitai[bot]
coderabbitai Bot reviewed Mar 19, 2026
View reviewed changes

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents 
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@CONTRIBUTING.md`:
- Around line 126-133: Replace the non-descriptive link text "here" in the
ProperDocs documentation paragraph with meaningful text (e.g., "ProperDocs
writing guide" or "ProperDocs user guide") so screen readers and users know what
the link points to; update the link text in the markdown paragraph that
currently reads the primer link and ensure the anchor text clearly describes the
destination.
🪄 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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: f164ca51-04ec-4e84-8612-68335d1a986b

📥 Commits

Reviewing files that changed from the base of the PR and between 33c7174 and 0460357.

⛔ Files ignored due to path filters (1)
  • uv.lock is excluded by !**/*.lock
📒 Files selected for processing (6)
  • .readthedocs.yaml
  • CONTRIBUTING.md
  • Makefile
  • make.cmd
  • properdocs.yml
  • pyproject.toml

Comment thread CONTRIBUTING.md Outdated
@PPsyrius PPsyrius mentioned this pull request Mar 19, 2026
Merged
9 tasks
@pareshjoshij

pareshjoshij commented Mar 19, 2026

Copy link
Copy Markdown
Contributor

Do I need to make any changes to my PR (#3282) regarding this? (Except for the make serve commands, which I am already going to drop anyway). ?

@PPsyrius

PPsyrius commented Mar 19, 2026

Copy link
Copy Markdown
Collaborator Author

@pareshjoshij Let me recheck just to be sure, but assuming that this got merged first, all the changes needed is for serve command from uv run --no-sync mkdocs serve to uv run --no-sync properdocs serve

@PPsyrius

PPsyrius commented Mar 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator Author

@pareshjoshij I've confirmed that it loads up correctly once you change all mkdocs serve to properdocs serve (but please don't do this yet until this PR is merged)
image

@pareshjoshij

pareshjoshij commented Mar 19, 2026

Copy link
Copy Markdown
Contributor

but please don't do this yet until this PR is merged

😄 yupp, Thanks !

@PPsyrius PPsyrius mentioned this pull request Mar 19, 2026
Closed
KJhellico
KJhellico previously approved these changes Mar 19, 2026
View reviewed changes

@KJhellico KJhellico left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. 👍 That was quick!

@sonarqubecloud

sonarqubecloud Bot commented Mar 21, 2026

Copy link
Copy Markdown

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

@arkid15r arkid15r enabled auto-merge March 21, 2026 17:20
arkid15r
arkid15r approved these changes Mar 21, 2026
View reviewed changes

@arkid15r arkid15r left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM
Thanks for addressing this!

@arkid15r arkid15r added this pull request to the merge queue Mar 21, 2026
Merged via the queue into vacanza:dev with commit d05ef3d Mar 21, 2026
32 checks passed
@PPsyrius PPsyrius deleted the properdocs_migration branch March 23, 2026 09:14
@coderabbitai coderabbitai Bot mentioned this pull request Apr 6, 2026
Merged
9 tasks
@KJhellico KJhellico mentioned this pull request Apr 6, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@coderabbitai coderabbitai[bot] coderabbitai[bot] left review comments

@arkid15r arkid15r arkid15r approved these changes

@KJhellico KJhellico KJhellico left review comments

Assignees

No one assigned

Labels

doc

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Address MkDocs may break support for all existing plugins and themes soon! warning

4 participants

@PPsyrius @pareshjoshij @arkid15r @KJhellico