fix: docs publication (multiversion)#435
Open
dgarcia360 wants to merge 3 commits intoscylladb:mainfrom
Open
Conversation
The jsdoc-include extension was looking for JSDoc HTML in the wrong folder during multiversion builds, so API pages came out empty on the published site.
There was a problem hiding this comment.
Pull request overview
Fixes multiversion docs publication by correcting how the jsdoc-include Sphinx extension resolves the JSDoc HTML output directory, so API reference pages aren’t rendered empty on the published site.
Changes:
- Resolve
jsdoc_html_dirrelative toenv.srcdir(instead ofenv.app.confdir) to match sphinx-multiversion build behavior. - Minor docstring formatting adjustment in
_resolve_jsdoc_dir.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
60
to
+61
| rel = config.jsdoc_html_dir or "../../public/docs" | ||
| return Path(env.app.confdir, rel).resolve() | ||
| return Path(env.srcdir, rel).resolve() |
There was a problem hiding this comment.
Switching the base from env.app.confdir to env.srcdir changes what jsdoc_html_dir is relative to. Please update the function/doc comments (and any referenced docs) to reflect the new behavior so users don’t keep configuring it “relative to conf.py” while the code resolves it relative to the Sphinx source dir (which may differ under sphinx-multiversion / -c).
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #433
Motivation
The
jsdoc-includeextension was looking for JSDoc HTML in the wrong folder during multiversion builds, so API pages came out empty on the published site.How to test
Run the following locally:
This should generate the API reference correctly, whereas previously it did not. Previously, it only worked if you ran
make previewbefore.After merging, verify that the docs are generated at nodejs-rs-driver.docs.scylladb.com/stable/api/Client.html