docs: migrate documentation from Sphinx/Read the Docs to VitePress with GitHub Pages deployment#146
Conversation
There was a problem hiding this comment.
Pull request overview
Migrates the project documentation from Sphinx/Read the Docs to a VitePress-based site published via GitHub Pages, with API reference pages generated from the Python source using pydoc-markdown.
Changes:
- Add a docs generation script (
pydoc-markdown→ Markdown) and wire it into VitePress build/dev commands. - Introduce a GitHub Pages deployment workflow for the VitePress site and update README badge/links.
- Remove the previous Sphinx/Read the Docs configuration and source files.
Reviewed changes
Copilot reviewed 20 out of 22 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/generate_docs.py |
New script to generate docs/api.md, docs/models.md, docs/exceptions.md via pydoc-markdown. |
pyproject.toml |
Ruff per-file ignore tweak for scripts/*. |
package.json |
Add docs scripts (generate/dev/build/preview) and VitePress dependency. |
package-lock.json |
Lockfile updates for VitePress and its transitive dependencies. |
docs/usage.md |
New Markdown usage page for VitePress docs. |
docs/index.md |
New VitePress home page frontmatter/content. |
docs/.vitepress/config.mts |
VitePress site configuration (nav/sidebar/search/base). |
README.md |
Switch documentation badge/link from Read the Docs to GitHub Pages. |
.github/workflows/deploy-docs.yaml |
New workflow to build and deploy docs to GitHub Pages. |
.prettierignore |
Ignore VitePress build artifacts and generated API docs. |
.gitignore |
Ignore VitePress build artifacts and generated API docs. |
.readthedocs.yaml |
Remove Read the Docs build configuration. |
docs/requirements.txt |
Remove Sphinx requirements. |
docs/Makefile |
Remove Sphinx Makefile. |
docs/make.bat |
Remove Sphinx Windows build script. |
docs/__init__.py |
Remove docs package marker (Sphinx-era). |
docs/source/conf.py |
Remove Sphinx configuration. |
docs/source/index.rst |
Remove Sphinx index page. |
docs/source/usage.rst |
Remove Sphinx usage page. |
docs/source/api.rst |
Remove Sphinx API module page. |
docs/source/models.rst |
Remove Sphinx models reference page. |
docs/source/__init__.py |
Remove docs source package marker (Sphinx-era). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
package.json
Outdated
| "docs:generate": "python3 scripts/generate_docs.py", | ||
| "docs:dev": "npm run docs:generate && vitepress dev docs", | ||
| "docs:build": "npm run docs:generate && vitepress build docs", | ||
| "docs:preview": "vitepress preview docs" |
There was a problem hiding this comment.
The docs:preview script runs vitepress preview docs without ensuring the site has been built first. Since vitepress preview serves the build output, this should typically depend on docs:build (and/or docs:generate) to avoid preview failing on a clean checkout.
| "docs:preview": "vitepress preview docs" | |
| "docs:preview": "npm run docs:build && vitepress preview docs" |
.github/workflows/deploy-docs.yaml
Outdated
| with: | ||
| python-version: "3.12" | ||
| - name: 🏗 Install pydoc-markdown | ||
| run: pip install pydoc-markdown |
There was a problem hiding this comment.
This workflow installs pydoc-markdown via pip install directly, which bypasses the repo’s existing uv-based, locked dependency approach used in other workflows. To make docs builds reproducible, consider adding pydoc-markdown to the project’s dev dependencies and using uv sync/uv run here as well (or at least pin the installed version).
| run: pip install pydoc-markdown | |
| run: pip install pydoc-markdown==4.8.2 |
There was a problem hiding this comment.
We don't use PIP, bu UV instead. :)
wmalgadey
added
documentation
|
There are some merge conflicts now, can you please have a look? :) |
…th GitHub Pages deployment - Replace Sphinx/Read the Docs with VitePress for documentation - Add GitHub Pages deployment workflow (triggered on main branch) - Auto-generate API docs from Python source code using pydoc-markdown - Add documentation deployment badge to README.md - Configure VitePress with search, base path, and proper styling Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Fix Tado() constructor usage example to use refresh_token - Add async_init() guidance for non-context-manager usage - Use absolute path for -I src in generate_docs.py - Add encoding='utf-8' to write_text() and ensure docs dir exists - Make docs:preview depend on docs:build - Use uv instead of pip for pydoc-markdown install in CI Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
nixel2007
force-pushed
the
feature/migrate-from-read-the-docs
branch
from
304c3f8 to
bfd87d1
Compare
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
nixel2007
force-pushed
the
feature/migrate-from-read-the-docs
branch
from
4750cb4 to
3ed14ed
Compare
Use pydoc-markdown YAML config with documented_only: false and render_typehint_in_data_header to display dataclass fields with their types. Filter out module-level imports while keeping class members. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add runtime introspection to enrich pydoc-markdown output with inherited methods (e.g. add_note, with_traceback for exceptions). Install project deps in CI via uv sync and run generate_docs.py through uv run for proper module resolution. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
You're making some progress here. Let me know when you deem it ready. Further improvement can be made via new PR's. :) |
|
@erwindouna this is ready for review |
|
I think this looks great and we can expand further on this. Thanks @nixel2007! |
Summary
Migrate the documentation system from Sphinx/Read the Docs to VitePress with GitHub Pages deployment.
Changes