Make CLI documentation searchable: Enable search for --options

[optimusprimeg]

Problem

Command-line options with double hyphens (like --run, --build-dir, --async) are currently not searchable in Sphinx documentation. This affects any project documenting CLI tools.

Example: Searching for --run in documentation returns results for 'run', even when the option is documented with '--run', because:

1. Sphinx's search splits on hyphens by default
2. Terms starting with - are treated as exclusion operators
3. --run becomes ["--", "run"] instead of staying as ["--run"]

Our Solution

We successfully fixed this for the KDE Builder documentation with a custom Sphinx extension that patches searchtools.js in three ways:

1. Preserve hyphens in splitting: Added \- to the word character regex
2. Fix exclusion logic: Prevent --options from being treated as exclusions (only single - should be)
3. Add debug logging: Help users verify search query parsing

The fix is automatic—it runs after every build via the build-finished hook.

Benefits to Sphinx Ecosystem

This would help any project documenting command-line tools:

• CLI applications (kubectl, git, docker, etc.)
• Build tools (cmake, make, ninja, etc.)
• Package managers (apt, pip, npm, etc.)
• System utilities

Implementation

We have a working implementation as a Sphinx extension (~100 lines). The extension:

• ✅ Preserves backward compatibility (no breaking changes)
• ✅ Works with existing themes
• ✅ Minimal performance impact
• ✅ Well-documented with inline comments

Video demonstration available

Questions

1. Would this be valuable as a built-in feature in Sphinx?
2. Should it be:
   • Always enabled?
   • A configuration option (e.g., preserve_hyphens_in_search = True)?
   • A separate extension?
3. Would you accept a PR for this feature?

Related

• Issue [search] Add ability to treat "-" as a normal letter, to not split search term into several words  #12400 - Similar request for command-line documentation
• Our implementation: Available upon request

Happy to provide more details, share the extension code, or create a PR if there's interest!

---

Note: This is based on real-world usage in KDE Builder documentation where searching for options like --build-dir, --async, and --branch-group now works perfectly.

[AA-Turner]

@optimusprimeg happy to accept a PR. Makes sense to treat double hyphen at least as special. The single hyphen case is trickier, though.

A

[optimusprimeg]

@AA-Turner @Ashark I’d like to propose a small, backwards-compatible convention for searching hyphen-prefixed tokens in Sphinx search. I was thinking in this way:

Keep the current meaning of -term = exclusion.
Introduce a simple escape for literal hyphens:

"\-r" → searches for -r
"\--run" → searches for --run
Just taking inspiration from BASH

This will avoid breaking '-' functionality while giving predictable way to search for hyphen-prefixed tokens.

[AA-Turner]

I'd honestly prefer a better fix, even if it has changes to the current syntax/semantics. Escaping with an arbitrary metachar isn't very discoverable.

cc @wlach if he has any thoughts here

A

[optimusprimeg]

Then just searching with hyphenated item in inverted commas like this "--run" will be more easier and discoverable
plus a tiny UI hint under the search box explaining this. That buys us immediate relief and time to design a better, discoverable syntax if we agree upon something else.

[wlach]

Quoting the term seems like the most intuitive approach to me. That's what I do with Google when I'm searching for a term like this. Should be a relatively straightforward addition to search tools.

[Ashark]

Yeah, exactly. The quotation was the first thing I tried when I saw that terms with hyphen are not working as expected.

[kaycebasques]

HI @optimusprimeg definitely interested in the extension you built. Please share the source code if you can.

P.S. it looks like your theme has adopted my search-as-you-type UI, nice!

[optimusprimeg]

Hi @kaycebasques good to hear you are interested currently i had solved for '--' search you can take a look on this thread of kde-builder.
https://invent.kde.org/sdk/kde-builder/-/merge_requests/104

[chishxd]

Hello there! I have tried working on this fix, It is just a minimal JS change, But I would like if somebody reviewed this code...

https://github.com/chishxd/sphinx/tree/feature-better-hyphens