sphinx

sphinx copied to clipboard

Is your feature request related to a problem? Please describe.

My problem is the search engine is not good at finding terms that are indexed, for example:

• https://docs.python.org/3/search.html?q=for should find https://docs.python.org/3/reference/compound_stmts.html#index-6
• https://docs.python.org/3/search.html?q=argument should find https://docs.python.org/3/glossary.html#term-argument
• https://docs.python.org/3/search.html?q=as should find https://docs.python.org/3/reference/compound_stmts.html#index-11 and a few others
• https://docs.python.org/3/search.html?q=function should find https://docs.python.org/3/glossary.html#term-function
• https://docs.python.org/3/search.html?q=pyobject should find https://docs.python.org/3/c-api/structures.html#c.PyObject ...

Describe the solution you'd like I think using the global index as a source for the search engine is a good way to enhance this and allow people to manually boost a search result by using the bang of the index directive. (.. index:: ! Python).

I can try to implement it, but I'm still not sure this is a good idea.

Generated Index can point to anchors, I'm not sure the current searchindex can hold them in its current state.

A non-python example, searching for ciphertext in pyca/cryptography, the glossary ciphertext term is pretty low on the page and hidden among mentions of it within autodoc pages.

There's also a bpo issue on that subject: https://bugs.python.org/issue42106

It provides more examples from the Python documentation

For instance if you search "append": https://docs.python.org/3/search.html?q=append

On my end, neither list nor MutableSequence appear anywhere on this page, even scrolling down.

Searching for "list": https://docs.python.org/3/search.html?q=list

The documentation for the builtin "list" object also doesn't appear on the page. Data Structures and built-in types appear below the fold and the former is genuinely useful but also very easy to miss (I had not actually noticed it before going back in order to get the various links and try to extensively describe the issue). Neither actually links to the list builtin type though.

Above the fold we find various "list" methods and classes from the stdlib as well as the PDB list comment, none of which seems like the best match for the query.

This would also be useful for the core CPython documentation.

A

Yeah, as discussed, this would be extremely useful for the CPython docs, as brought up in python/cpython#60075 , python/cpython#89541 , python/cpython#86272, python/cpython#86272 and probably others, so it would be fantastic if you could implement this. To be honest, it confuses me why the search index wouldn't include the...index...to begin with, heh.

I was going to offer to help, but I'm sure you'd do a far better job than I would. If you do need something within my (limited) skillset, like testing this or reviewing docs, etc, let me know. Thanks!

A draft implementation is at #10819. This issue suggests using the genindex source directly, whilst that is possible it ties to the builder a little too much for my liking.

A

Testing of the PR would be appreciated!

A