Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add readthedocs javascript search #158

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

ReenigneArcher
Copy link

@ReenigneArcher ReenigneArcher commented Aug 7, 2024

This PR adds a custom readthedocs search extension using javascript. I found the default doxygen search is quite terrible, and doesn't seem to actually search any markdown files (or barely searches them)... which is not great when you have user documentation.

I have added this for my own projects (here: LizardByte/doxyconfig#4), and figured I could share it back here for others to benefit from. A live preview is available here: https://docs.lizardbyte.dev/projects/doxyconfig/latest/search.html?query=doxygen

This is what it looks like.
image

image

Old version

image

image

The styling is somewhat based on Furo, this is how that looks in one of my projects.
image

TODO:

  • improve the appearance/layout of the anchor urls
  • possibly add live searching (This is above my capability for now, maybe it could be part of a later PR).

@ReenigneArcher ReenigneArcher force-pushed the feat-add-readthedocs-javascript-search branch from 6989243 to b2a87fc Compare August 7, 2024 18:46
@ReenigneArcher ReenigneArcher marked this pull request as ready for review August 7, 2024 18:49
@ReenigneArcher
Copy link
Author

ReenigneArcher commented Aug 7, 2024

A user of mine reported there is an issue with the search results page on mobile. I don't think it's anything related to my code, but possibly a doxygen bug?

When the user clicks the search bar, the keyboard pops up, but then immediately closes... and there is no way to enter a search term. I know doxygen generates search pages slightly differently depending on the variable search config options. Seems to work perfectly fine on desktop though.

This code is in the original doxygen search.js, so maybe something to do with this.

function SearchBox(name, resultsPath, extension) {
  this.DOMSearchField = () => document.getElementById("MSearchField");
  this.DOMSearchBox = () => document.getElementById("MSearchBox");
  this.OnSearchFieldFocus = isActive => {
    if (isActive) {
      this.DOMSearchBox().className = 'MSearchBoxActive';
    } else {
      this.DOMSearchBox().className = 'MSearchBoxInactive';
    }
  }
}

Copy link
Owner

@jothepro jothepro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool! The readthedocs search seems to work a lot better indeed! I think adding this as an extension to the theme would be really valuable!

When starting the search with the readthedocs addon widget at the bottom right, a really nice popover with live search is opened. IMO that's a really nice user experience! Do you think it would be possible to use the searchbar in the upper right just as a link that opens this popover?

Comment on lines +31 to +33
"devDependencies": {
"jquery": "^3.7.1"
},
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

was jquery intentionally listed as a devDependency here? Currently the package.json is only used to allow for installation of the custom CSS. Can you explain your development workflow that requires the dependency to be added here?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, otherwise the IDE complains about undefined names, such as ajax if I recall.

@ReenigneArcher
Copy link
Author

When starting the search with the readthedocs addon widget at the bottom right, a really nice popover with live search is opened. IMO that's a really nice user experience! Do you think it would be possible to use the searchbar in the upper right just as a link that opens this popover?

I'm not sure I fully understand the ask, but if you're just asking if the live search will work (search as you type)... it's possible, I just don't know how to implement it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants