CI: Add job to test docs build #12
Conversation
glensc
force-pushed
the
docs-build-check
branch
from
a4771dc to
fac3854
Compare
glensc
force-pushed
the
docs-build-check
branch
from
b7d453d to
99fcd18
Compare
glensc
force-pushed
the
docs-build-check
branch
from
99fcd18 to
2320aae
Compare
WalkthroughA new GitHub Actions workflow named "Pull Request Docs Check" has been introduced to the repository. This workflow is triggered on pull requests and pushes to the main branch when changes are made to the workflow file or any files within the docs directory. It runs on an Ubuntu 22.04 environment and includes steps for checking out the code, setting up Python, installing dependencies, and building documentation. Additionally, modifications were made to the test workflow to ignore specific paths, refining the conditions under which tests are executed. Changes
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
.github/workflows/docs-build.yml (2)
21-24: Update Python setup action versionThe workflow uses an older version of setup-python action.
- uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: ${{ env.DEFAULT_PYTHON }} + cache: pip # Enable pip caching for faster builds🧰 Tools
🪛 actionlint (1.7.4)
22-22: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
28-32: Add error handling for version extractionThe version extraction process needs error handling in case there are no tags.
- # Setup version - version=$(git describe --tags --abbrev=0) - echo "__version__ = '$version'" > trakt/__version__.py - cat trakt/__version__.py - python -c "from trakt import __version__; print(__version__)" + # Setup version + if ! version=$(git describe --tags --abbrev=0 2>/dev/null); then + version="0.0.0-dev" + echo "No git tags found, using default version: $version" + fi + echo "__version__ = '$version'" > trakt/__version__.py + cat trakt/__version__.py + python -c "from trakt import __version__; print(__version__)"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📥 Commits
Reviewing files that changed from the base of the PR and between 43e281f and 2320aae911583e4b8528c94ca4251cfcf60ff3af.
📒 Files selected for processing (2)
.github/workflows/docs-build.yml(1 hunks).github/workflows/test.yml(1 hunks)
🧰 Additional context used
🪛 actionlint (1.7.4)
.github/workflows/docs-build.yml
20-20: the runner of "actions/checkout@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
22-22: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
🔇 Additional comments (1)
.github/workflows/test.yml (1)
5-8: Verify documentation and test independenceThe paths-ignore configuration looks good, but please verify that documentation changes cannot affect tests. For example:
- Are there any executable code examples in docs that should be tested?
- Is documentation generated from docstrings that are used in tests?
Let's check for potential dependencies:
Also applies to: 10-13
✅ Verification successful
Documentation changes can be safely ignored for tests
The paths-ignore configuration is correct. Analysis shows:
- Documentation uses standard Sphinx setup without executable examples
- No integration between documentation and test suite
- No docstring-based documentation that could affect tests
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Check for executable code in docs and doctest usage rg -l ".. code-block::" docs/ || true rg -l "doctest" . || trueLength of output: 72
Script:
#!/bin/bash # Check Makefile and look for additional patterns cat docs/Makefile echo "---" # Look for Python test files in docs fd -e py . docs/ echo "---" # Search for documentation generation tools rg -l "sphinx|pdoc|doxygen|jsdoc|typedoc" . || trueLength of output: 6934
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
.github/workflows/docs-build.yml (3)
1-1: Consider standardizing the workflow nameFor consistency with GitHub's naming conventions, consider using "Docs" or "Documentation" instead of "Pull Request Docs Check" since the workflow runs on both PRs and pushes.
-name: "Pull Request Docs Check" +name: "Documentation"
15-16: Consider upgrading to Python 3.11Python 3.11 is the latest stable version with significant performance improvements. Consider upgrading unless there are specific compatibility requirements with 3.10.
- DEFAULT_PYTHON: "3.10" + DEFAULT_PYTHON: "3.11"
41-41: Add error handling for docs buildThe
make docscommand should fail the workflow if documentation build fails. Consider adding error handling and artifact upload.- make docs + make docs || { + echo "::error::Documentation build failed" + exit 1 + } + - name: Upload documentation + if: always() + uses: actions/upload-artifact@v4 + with: + name: documentation + path: docs/_build/ + if-no-files-found: error
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📥 Commits
Reviewing files that changed from the base of the PR and between 2320aae911583e4b8528c94ca4251cfcf60ff3af and cf1cecf90fa4d564a87b88c7cb31c1e71fa49f5c.
📒 Files selected for processing (1)
.github/workflows/docs-build.yml(1 hunks)
🧰 Additional context used
🪛 actionlint (1.7.4)
.github/workflows/docs-build.yml
23-23: the runner of "actions/checkout@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
25-25: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
🔇 Additional comments (2)
.github/workflows/docs-build.yml (2)
22-23: Update checkout configuration for version extractionSince the workflow extracts version from git tags, we need to ensure tags are fetched. Also, update to the latest version as recommended by actionlint.
- uses: actions/checkout@v3 + uses: actions/checkout@v4 + with: + fetch-depth: 0 # Fetch all history and tags🧰 Tools
🪛 actionlint (1.7.4)
23-23: the runner of "actions/checkout@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
38-41: Improve dependency installation reliabilityThe current approach has several potential issues:
- Direct apt install of sphinx might get an outdated version
- Missing pip install of sphinx and its dependencies
- No version pinning for sphinx
- # Install deps and build docs - pip install -r requirements.txt - sudo apt install sphinx + # Install deps and build docs + python -m pip install --upgrade pip + python -m pip install -r requirements.txt + python -m pip install 'sphinx>=7.1.0' # Pin to a specific version
glensc
force-pushed
the
docs-build-check
branch
from
7711e98 to
8285ff8
Compare
glensc
force-pushed
the
docs-build-check
branch
2 times, most recently
from
7f140f9 to
97b6a80
Compare
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
glensc
force-pushed
the
docs-build-check
branch
from
97b6a80 to
6e1f012
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (3)
.github/workflows/docs-build.yml (3)
22-29:⚠️ Potential issueUpdate GitHub Actions to latest versions
Both actions need version updates:
- uses: actions/checkout@v3 + uses: actions/checkout@v4 - uses: actions/setup-python@v4 + uses: actions/setup-python@v5🧰 Tools
🪛 actionlint (1.7.4)
23-23: the runner of "actions/checkout@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
27-27: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
34-37:⚠️ Potential issueImprove version extraction error handling
The current version extraction could fail if no tags exist. Consider adding a fallback:
- version=$(git describe --tags --abbrev=0) || exit 1 + version=$(git describe --tags --abbrev=0 2>/dev/null || echo "dev")
39-42:⚠️ Potential issueImprove dependency installation process
The current approach needs improvement:
- Direct apt install of sphinx might get an outdated version
- Missing pip install of sphinx and its dependencies
- No version pinning for sphinx
- pip install -r requirements.txt - sudo apt install sphinx + python -m pip install --upgrade pip + python -m pip install -r requirements.txt + python -m pip install 'sphinx>=7.1.0'
🧹 Nitpick comments (2)
.github/workflows/docs-build.yml (2)
1-17: Consider workflow naming convention and Python version updates
- Consider renaming the workflow to be more consistent with CI naming conventions:
-name: "Pull Request Docs Check" +name: "docs"
- Consider upgrading to Python 3.11 (latest LTS) for better performance and features:
- DEFAULT_PYTHON: "3.10" + DEFAULT_PYTHON: "3.11"
42-42: Add error handling for documentation buildThe
make docscommand should include error handling and verbose output for better debugging:- make docs + make docs SPHINXOPTS="-W --keep-going -n"The added options will:
-W: Turn warnings into errors--keep-going: Don't stop on first error-n: Run in nit-picky mode
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📥 Commits
Reviewing files that changed from the base of the PR and between cf1cecf90fa4d564a87b88c7cb31c1e71fa49f5c and 6e1f012.
📒 Files selected for processing (2)
.github/workflows/docs-build.yml(1 hunks).github/workflows/test.yml(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- .github/workflows/test.yml
🧰 Additional context used
🪛 actionlint (1.7.4)
.github/workflows/docs-build.yml
23-23: the runner of "actions/checkout@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
27-27: the runner of "actions/setup-python@v4" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
Take recommendations from coderabbit to accoiunt: - #12
No description provided.