python / python/cpython

Ordering of search results in the docs could be improved

Aberta
#138,277 4 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

docs triaged
Linguagem predominante
Python
Estrelas
77.2k
Forks
35.9k
Métricas de merge de PRs
Métricas de PR pendentes

Descrição

When searching for "str" in the documentation, for example, the built-in str type shows up 44th in the list of results currently. This specific example (as well as a general notion that the search results are often not useful) was recently cited to me by a colleague as one reason that they choose to caution beginner students against using Python's docs compared to other alternatives, because the docs are "hard to navigate" and "hard to search." I disagree with that assessment on the whole, but I do think that improving the ordering of the search results would make the docs easier to use and navigate, particularly for folks just starting out with Python.

Sphinx has a mechanism for custom sorting of search results, so it should be possible to come up with some heuristics there that improve the ordering of the results. I'll put in a PR in a little while with one small step that I think is an improvement.

Linked PRs
  • gh-138278

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Direção de pesquisa

Revise o PR gh-138278 vinculado e o mecanismo personalizado de ordenação dos resultados de busca do Sphinx mencionado na issue. Use o exemplo de busca "str" como verificação inicial e considere o trabalho concluído quando a ordenação resultante for comprovadamente mais útil para os usuários da documentação.

Escrita pelo modelo de indexação a partir do texto da issue.

Avaliação

Stack de tecnologia
python
Domínio
documentation, search
Tipo de issue
Funcionalidade
Dificuldade
5/5
Tempo estimado
Mais de uma semana
Status de atividade
Estagnada
Clareza
Razoavelmente clara
Facilidade para iniciantes
20/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.