Working readthedocs - #2222
Open
sahags wants to merge 23 commits into
Open
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds a “Smart Search” page to the ProDy documentation and wires in a JavaScript-based exact-match redirect using a generated api_index.json during the Sphinx build, improving function lookup behavior on Read the Docs.
Changes:
- Added a new docs page (
smart_search.rst) with an HTML form for function-name lookup. - Included a new static JS asset (
_static/smart_search.js) and configured Sphinx (conf.py) to load it and generate_static/api_index.jsonafter a successful build. - Added a standalone Python indexing script (
docs/tools/build_api_index.py) that also writesapi_index.json.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/tools/build_api_index.py | Adds a standalone script to generate an API index JSON (currently mismatched with runtime expectations). |
| docs/smart_search.rst | Introduces the Smart Search documentation page and embedded HTML form. |
| docs/index.rst | Adds smart_search to the documentation toctree. |
| docs/conf.py | Loads smart_search.js and generates _static/api_index.json from objects.inv at build-finished. |
| docs/_static/smart_search.js | Implements client-side exact-match redirect with fallback to Sphinx search. |
Comments suppressed due to low confidence (2)
docs/smart_search.rst:18
- The generated status text is dynamically updated by JS, but this element isn’t marked as a live region. Adding an aria-live attribute makes the feedback discoverable to screen readers.
<p id="smartSearchStatus" style="margin-top:10px; opacity:0.8;"></p>
docs/tools/build_api_index.py:70
- This script writes api_index.json as a list of {name, qualname}, but the runtime smart_search.js (and the Sphinx build hook in docs/conf.py) expects api_index.json to be an object containing exact_simple/exact_full URL maps. If this script is intended to be used, the output format needs to be aligned; otherwise it’s dead/legacy tooling that will mislead future maintainers.
with out_file.open("w", encoding="utf-8") as f:
json.dump(results, f, indent=2)
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+106
to
+110
| import os | ||
| import sys | ||
| import json | ||
| import os | ||
| from sphinx.util.inventory import InventoryFile |
Comment on lines
+13
to
+15
| <input id="smartSearchInput" | ||
| placeholder="Enter function name (e.g. parsePDB)" | ||
| style="width:100%; padding:10px; font-size:16px;" /> |
Comment on lines
+2
to
+6
| import json | ||
| import os | ||
| import sys | ||
| import importlib | ||
| from pathlib import Path |
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.
Updated readthedocs searching