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

[Ashark]

I would like also to be able to use a single hyphen when I search specifically for that. For example, I want to find literally -r. If it is unavoidable to treat hyphen in the beginning of word as an exclusion term, then possibly introduce a way to escape that? For example, using double quotes, like this: "-r".