Add documentation using sphinx and github pages (Codex) - #45
Conversation
- Rollback to sphinx with pydata theme - Add configuration for sphinx - Implement bash scripts to manage and build documentation + CI for github pages - Update md and templates for documentation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 032809fee0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| python -m sphinx -b html "${source_root_}/doc" "${OUTPUT_DIR}/${output_name_}"; then | ||
| echo "Skipping ${version_name_}: Sphinx build failed" | ||
| rm -rf "${OUTPUT_DIR:?}/${output_name_}" |
There was a problem hiding this comment.
The build_docs_ helper suppresses Sphinx errors by catching a failed build, deleting the output folder, and continuing, and this same path is used for the stable build. On a main or tag push with a docs breakage, the workflow can still pass and deploy an incomplete site (including a root redirect to stable/), which hides the regression instead of failing CI. stable generation should be treated as required and exit non-zero on failure.
Useful? React with 👍 / 👎.
| if [ "${version_name_}" != "stable" ] && [ ! -f "${source_root_}/doc/_static/switcher.json" ]; then | ||
| echo "Skipping ${version_name_}: versioned docs config not found" | ||
| return 0 |
There was a problem hiding this comment.
This gate skips every non-stable version unless doc/_static/switcher.json exists in that tag checkout, but this commit generates switcher.json into the output site later and does not require a source copy in tags. As a result, historical tag builds are systematically skipped and the published version switcher cannot include those versions even though the workflow says it builds versioned docs.
Useful? React with 👍 / 👎.
| --with-explain) | ||
| add_extra "explain" | ||
| shift |
There was a problem hiding this comment.
The installer adds extras like explain/explain-shap/explain-captum via CLI flags, but this commit’s pyproject.toml only defines cuda_all, test, and docs optional dependency groups. Passing these flags produces pip install .[...] with unknown extras and fails installation, so advertised install modes are broken for users who follow those options.
Useful? React with 👍 / 👎.
1 participant
Description
This PR renews the documentation of the library and moves the CI to github pages from Read The Docs. Sphinx with pydata theme is used. Documentation includes installation guide, examples and usage guides for relatively stable modules.