ldoc
ldoc copied to clipboard
lunarmodules
Search function
Hello, a simple search function would do wonders for usability. Something like naturaldocs' search would be fine.
Here's an example. http://www.naturaldocs.org/documentation/html/files/NaturalDocs-.html
A workaround would be to add a custom Google search engine or something similar through a custom template.
Is there a way to do so without specifying the whole HTML template itself?
Has anyone tried integrating searching scripts like these into ldoc?
- Fullproof: http://reyesr.github.io/fullproof/
- Lunr.js: http://lunrjs.com/
The easiest would be to teach LDoc to build a good index of functions/methods/tables, which can be searched in the old-fashioned way. The page currently called 'index' isn't really that ;)
For readmes, topics and 'narrative' documentation in general, browser search is often good enough, but I'm open to options. I would certainly like to make such customizations easier!
We could also incorporate Bootstrap into the HTML template and produce a single HTML page that contains all the modules and leverage any browser's built-in search feature. Example: http://getbootstrap.com/getting-started
That also helps modernize the presentation and make it more mobile-friendly (i.e. different screen sizes).
One thing that could work is create alternative templates for users to experiment with more modern layouts.
Contributions welcome.
I would suggest this functionality should be made available independent of the theme. There are several client side search options that could be used, but I wouldn't pair it with one that also dictated the front end layout. Instead one we should use one where we can generate an static index at docs build time that can be used by a client side search ui to provide results.
I think the first step should be to allow ldoc to output .lua (or .json) version of the doc content alongside the .html. This would allow post-processing tools to both generate the static search index and another post processing tool to generate LSP friendly files for auto-completion. Plus, it solves the "remove the sandbox" problem/issues/PRs in a cleaner way since people will just be free to do whatever they want in their post-processing nodes.
Then you can use the resulting search JS code in a custom ldoc template. I don't think hardcoding a search feature into ldoc itself is going to age well. The "best" indexer will change much faster than ldoc development speed.
@alerque If I do that, will it be merged or sit unreviewed for 5 years because it's going to be a rather large change? I will not break backward compat and will support the changes over long term.
I'd help facilitate a PR that output a data dump format like JSON (or a serialized Lua table) that made it possible to post process for other purposes. And since I'm traveling it might not get merged inside of a week but it should be a lot less than 5 years! That kind of lag time is why I volunteered to help maintain this in the first place and why it got moved to this org. If I can't keep up we'll try to get more maintainers on broad here.