Skip to content

ENH 5.3 - Implement Sphinx documentation with CI integration#15

Open
xandie985 wants to merge 15 commits intomainfrom
enh/doc_deployments
Open

ENH 5.3 - Implement Sphinx documentation with CI integration#15
xandie985 wants to merge 15 commits intomainfrom
enh/doc_deployments

Conversation

@xandie985
Copy link
Copy Markdown
Collaborator

@xandie985 xandie985 commented Jul 3, 2025 •
edited
Loading

Changes:

  • Added Sphinx configuration in /docs
  • Configured documentation theme and extensions
  • Added CI job for documentation building
  • Set up GitHub Pages deployment
  • Updated README with local build instructions

Testing:

  • Verified local build with pip install -e ".[docs]" && cd docs && make html
  • Confirmed CI build passes/fails appropriately
  • Checked GitHub Pages deployment

Notes:

@xandie985 xandie985 self-assigned this Jul 3, 2025
@xandie985 xandie985 added documentation Improvements or additions to documentation enhancement New feature or request ci/cd for tasks related to ci/cd labels Jul 3, 2025
@xandie985 xandie985 mentioned this pull request Nov 6, 2025
Open
6 tasks
@xandie985
fix(docs): include core dependencies in docs extra for autodoc imports
6f7e743 
- Add pandas, numpy, torch, scipy, scikit-learn to docs_requires
- Ensures autodoc can import modules during documentation build
- Fixes ModuleNotFoundError warnings in CI/CD build logs
@xandie985
fix(docs): restore Sphinx packages and add all core dependencies
934ee6b 
- Add sphinx>=7.0.0, myst-parser>=4.0.0, sphinx_pdj_theme>=0.4.0
- Ensure all core dependencies (pandas, numpy, torch, scipy, scikit-learn) are in docs_requires
- Fixes autodoc import failures in CI/CD documentation build
@xandie985
ci: clean build artifacts before documentation generation
1b9a11a 
- Remove docs/_build, docs/_autosummary, and generated .rst files
- Ensures fresh build without cache interference
- Prevents stale documentation from being deployed
- Applies to both docs.yml and python-package.yml workflows
@xandie985
fix(ci): ensure deploy-docs runs after successful build
e1e28cc 
- Add success() check to deploy-docs if condition
- Ensures deployment only runs when build-docs completes successfully
- Fixes skipped deployment issue
@xandie985
fix(docs): comprehensive autodoc import fixes for CI/CD
2a1349a 
- Add debug logging to verify package installation and imports
- Set PYTHONPATH explicitly for sphinx-apidoc and build steps
- Add autodoc_mock_imports for problematic dependencies
- Ensure dsipts package is properly accessible during documentation build
- Should resolve empty API docs on server vs populated docs locally
@xandie985
fix(docs): include ALL core requirements in docs extra
b9f8ca8 
Critical fix:
- docs_requires now includes ALL core_requirements (not just subset)
- Ensures pip install -e '.[docs]' installs pandas, numpy, torch, etc.
- Simplified workflow with minimal verification step
- Removed unnecessary mock imports since all deps are installed

This fixes ModuleNotFoundError for pandas and other core dependencies during CI/CD autodoc generation.
@xandie985
fix(pyproject): add ALL core dependencies to docs extra
d7c8cf8 
CRITICAL FIX:
- pyproject.toml was overriding setup.py with minimal docs dependencies
- Updated docs extra to include ALL 27 dependencies (Sphinx + core packages)
- Now pip install -e '.[docs]' will install pandas, numpy, torch, etc.
- This was the root cause of ModuleNotFoundError in CI/CD

The pyproject.toml takes precedence over setup.py for modern Python packaging.
@xandie985
refactor(ci): remove duplicate docs job from python-package workflow
d12db55 
- Remove redundant docs job from python-package.yml
- Documentation building is handled by dedicated docs.yml workflow
- Reduces duplicate CI/CD jobs and confusion
- Simplifies workflow: test → build (no docs in between)
- Keeps docs.yml as single source of truth for documentation
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@xandie985 xandie985

Labels

ci/cd for tasks related to ci/cd documentation Improvements or additions to documentation enhancement New feature or request

Projects

DSIPTS_PTF_board
Status: No status

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@xandie985