39 explore automatic documentation generation#53
Conversation
Add sphinx, pydata-sphinx-theme, myst-parser, and numpydoc as optional dependencies in a docs group. Add docs/_build/ to .gitignore.
Add conf.py with pydata-sphinx-theme, numpydoc, autodoc, intersphinx, and mocked imports for sklearn/numpy/scipy. Add landing page, getting started guide, and API reference page.
Add Taskfile tasks to build the Sphinx documentation and serve it locally on port 8000.
Add documentation page listing supported scikit-learn estimators by category, unsupported estimators, chemotools integration, and available serialization formats.
Convert See Also section to References with proper numbered citations. Rename Developer Notes to Notes to match numpydoc conventions.
There was a problem hiding this comment.
Pull request overview
This PR introduces Sphinx-based documentation for OpenModels and adds an automated GitHub Pages deployment workflow, along with small docstring tweaks to better match scikit-learn/numpydoc conventions.
Changes:
- Add a Sphinx docs site (MyST Markdown + pydata-sphinx-theme + numpydoc) and new documentation pages.
- Add a GitHub Actions workflow to build and deploy docs to GitHub Pages.
- Update
SklearnSerializerdocstring sections to useReferences/Notesformatting.
Reviewed changes
Copilot reviewed 9 out of 12 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| pyproject.toml | Adds an optional Poetry docs dependency group for Sphinx tooling. |
| openmodels/serializers/sklearn/sklearn_serializer.py | Docstring formatting updates for numpydoc-style sections. |
| docs/index.md | New docs landing page + toctree, includes quick-start snippet. |
| docs/getting_started.md | New getting-started guide with example usage. |
| docs/supported_models.md | New supported-models overview and custom estimator guidance. |
| docs/api.md | New API reference page using Sphinx autodoc. |
| docs/conf.py | Sphinx configuration (extensions, theme, intersphinx, etc.). |
| Taskfile.yml | Adds tasks to build/serve docs locally. |
| .gitignore | Ignores Sphinx build output directory. |
| .github/workflows/docs.yml | Adds CI workflow to build and deploy docs to GitHub Pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
| push: | ||
| branches: | ||
| - main | ||
| - 39-explore-automatic-documentation-generation | ||
| workflow_dispatch: |
There was a problem hiding this comment.
I think we can accept this one, or delete the branch after merging and clean the docs.yml in the next PR
| - uses: actions/checkout@v6 | ||
|
|
||
| - name: Set up Python | ||
| uses: actions/setup-python@v6 |
There was a problem hiding this comment.
I don't think this is good enough argument to downgrade the versions of the actions (some of them two versions) I would ignore this comment
| docs:html-all: | ||
| desc: Build the Sphinx documentation (clean + full rebuild) | ||
| cmds: | ||
| - "poetry run sphinx-build -b html docs docs/_build/html" |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
| project = "OpenModels" | ||
| copyright = "2026, Alejandro Gutierrez and Raúl Marín" | ||
| author = "Alejandro Gutierrez, Raúl Marín" | ||
| release = "0.1.0-alpha.21" |
There was a problem hiding this comment.
Now I see the version here, just a small note: We might update the version (also in pyproject.toml) before merging to 0.1.0-alpha.22, since we have a workflow that publish main in TestPyPI (check ci.yml).
This approach has a real friction point: every merge to main requires a version bump or CI breaks. I think we should change this some how...
There was a problem hiding this comment.
Good point! I'll remove it :)
sklearn-like documentation