search

KhronosGroup / Vulkan-Site

Vulkan Documentation Project framework for integrated documentation site with spec, proposals, guide, and more
Other
25 stars 2 forks source link

Prioritize refpages/function documentation in search results #52

Open r-potter opened 8 months ago

r-potter commented 8 months ago

When searching for Vulkan commands, is there any way to prioritize the actual function definition in the main spec? For example, searching for vkCreateInstance currently returns me 14 results, none of which are the actual definition of the entrypoint and it's corresponding documentation.

oddhack commented 8 months ago

The function definition seems to be in the search index, so something about the way it's written must be giving it low priority. There doesn't seem to be much control over this in lunr or the Antora Lunr extension - there are a few lunr parameters but it isn't obvious how they would help here. We might have to synthesize some sort of (normally invisible) text the indexer can grab for refpage blocks.

I have considered integrating the separate refpages into the Antora site as a separate component. It would not be difficult but I'm not sure all that content duplication is helpful. Web search engines typically (or at least often) point people towards the refpages today.

oddhack commented 8 months ago

See https://antora.zulipchat.com/#narrow/stream/312271-users.2Flunr-extension/topic/Prioritizing.20pages.20for.20a.20query/near/397491372 for my query to the Antora dev community.

oddhack commented 8 months ago

I'm starting to get a handle on this. Lunr doesn't process the HTML itself, it relies on something to marshall the data into a JSON file. For asciidoctor, we have a script config/chunkindex/generate-index.html which runs on the HTML chapter files and adds the API name anchors specifically as tagged constructs to be indexed. For Antora, the advice I've been getting is to turn every API name into its own separate section title/anchor, which is hideously impractical - some of our documents would end up with many hundreds of sections, and it would be massively intrusive on the spec markup.

But I'm pretty sure we can tweak the Antora Lunr Extension, which I assume is what's doing the JSON marshalling, to do the same thing that our indexer does. For comparison see e.g. https://registry.khronos.org/vulkan/specs/1.3-extensions/html/index.html and put vkCreateInstance in the searchbox - it comes up at the top, as desired.