Docs doesn't make it clear that pickers and extensions accept same opts as defaults

[clorl]

Description

I've been diving into telescope recently, as I've been using it for some time but never configured it thoroughly. I read the entire :h manual inside Neovim.

I hard a hard time understanding what options the individual pickers or extensions passed into setup() could take. It took me a while to understand that a picker's config table accepts the same keys as "defaults" table plus its own config keys which are shown in telescope.builtin. Writing it down I understand that it's kinda implied that defaults can be overriden, but it took me some time to fully get how it works.

Do you think this warrants a little clarification ?

In my humble opinion, it'd be worth modifying the telescope.setup section and the telescope.builtin section, here is my opinion on the parts the documentation is lacking clarity, as well as my humble proposal. I'd love to hear your feedbacks on this.

:h telescope.setup()

telescope.setup({opts})                                    *telescope.setup()*
    Setup function to be run by user. Configures the defaults, pickers and
    extensions of telescope.

    Usage:
    >
    require('telescope').setup{
      defaults = {
        -- Default configuration for telescope goes here:
        -- config_key = value,
        -- ..
      },
      pickers = {
        -- Default configuration for builtin pickers goes here:
        -- picker_name = {
        --   picker_config_key = value,
        --   ...
        -- }
        -- ADD: Each picker table accepts the same opts as the defaults table.
        -- ADD: On top of those, the pickers each have additional opts, which
        -- ADD: you can learn about in telescope.builtin.
        -- ADD: Options set here will be applied every time you call this builtin picker
        -- DEL: Now the picker_config_key will be applied every time you call this
        -- DEL: builtin picker
      },
      extensions = {
        -- Your extension configuration goes here:
        -- extension_name = {
        --   extension_config_key = value,
        -- }
        -- ADD: Just like builtin pickers, extension can take the same opts as the
        -- ADD: the defaults table in order to override them.
        -- please take a look at the readme of the extension you want to configure
      }
    }

    Valid keys for {opts.defaults}
    ADD: (Those keys are also valid for builtin pickers and extensions)

    -- And then the list of opts possible keys

I have to note that the builtin part of the builtin help kinda implies this but it doesn't state it clearly. What I struggled to understand is that the builtin pickers options extend the default ones. Maybe this section could be clarified? :h telescope.builtin

To use any of Telescope's default options or any picker-specific options, call
your desired picker by passing a lua table to the picker with all of the
options you want to use. Here's an example with the live_grep picker:

>
  :lua require('telescope.builtin').live_grep({
    prompt_title = 'find string in open buffers...',
    grep_open_files = true
  })
  -- or with dropdown theme
  :lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{
    previewer = false
  })

Neovim version

NVIM v0.10.1
Build type: Release
LuaJIT 2.1.1713484068

Operating system and version

Debian 12

Telescope version / branch / rev

0.1.X

checkhealth telescope

telescope: health#telescope#check

Checking for required plugins ~
- OK plenary installed.
- OK nvim-treesitter installed.

Checking external dependencies ~
- OK rg: found ripgrep 14.1.0 (rev 47797d5476)
- WARNING fd: not found. Install [sharkdp/fd](https://github.com/sharkdp/fd) for extended capabilities

===== Installed extensions ===== ~

Telescope Extension: `conflicts` ~
- No healthcheck provided

Telescope Extension: `dap` ~
- No healthcheck provided

Telescope Extension: `luasnip` ~
- No healthcheck provided

Telescope Extension: `ui-select` ~
- No healthcheck provided

Steps to reproduce

1. :h telescope

Expected behavior

No response

Actual behavior

See desc

Minimal config

local root = vim.fn.fnamemodify("./.repro", ":p")

-- set stdpaths to use .repro
for _, name in ipairs { "config", "data", "state", "cache" } do
  vim.env[("XDG_%s_HOME"):format(name:upper())] = root .. "/" .. name
end

-- bootstrap lazy
local lazypath = root .. "/plugins/lazy.nvim"
if not vim.uv.fs_stat(lazypath) then
  vim.fn.system {
    "git",
    "clone",
    "--filter=blob:none",
    "https://github.com/folke/lazy.nvim.git",
    lazypath,
  }
end
vim.opt.runtimepath:prepend(lazypath)

-- install plugins
local plugins = {
  {
    "nvim-telescope/telescope.nvim",
    dependencies = {
      "nvim-lua/plenary.nvim",
    },
    config = function()
      -- ADD INIT.LUA SETTINGS THAT ARE _NECESSARY_ FOR REPRODUCING THE ISSUE
      require("telescope").setup {}
    end,
  },
}

require("lazy").setup(plugins, {
  root = root .. "/plugins",
})

[jamestrew]

I agree, there's a lot to be desired in our help docs.

There is a lot of inheritance with the options of the pickers and a lot of it is undocumented largely because with our current documentation generation tooling, there isn't a really clean, non-cumbersome way to express these inheritances. I'm working on a tooling upgrade for our docgen and once that's through, I'm looking to revamp our docs a fair bit. I'll take this feedback into consideration when I'm doing this, thanks.

[clorl]

Thanks for the kind reply, really happy to help. As a temporary solution, maybe this could be clarified somewhere in the README or Wiki, and mentioned in the telescope.setup help section? I'll let you be the judge of that

[jamestrew]

Yeah if you're interested, by all means, I will welcome these clarifications. You're suggestions to the :h telescope.setup() look good to me for the most part and it will also apply to the README as well.

[clorl]

I'll make a PR soon if you're okay with it. Then, I will have the glory to have a PR named "Changed README" merged to my name, and I think that is a life-goal

[clorl]

I've started writing my PR and I'm looking into setup and pickers code to make sure which keys are valid for pickers and which aren't.

For this particular PR, I will propose only static changes to the docs, no additional code, but since defaults options are dynamically generated, I could add a lookup to see if the key is valid for pickers. It would involve something like this

-- init.lua -- This is pseudocode
telescope.__format_setup_keys = function()
  -- My first idea is having telescope.pickers have a list 
  -- of accepted options as a hint for the docs. This could be also a local table
  -- in this function, as it's a temporary workaround
  local picker_compatible_keys = require("telescope.pickers").__docs_get_valid_keys()
  for _, name in ipairs(names) do
    -- *snip* Current code that makes descriptions 
    if table.contains(picker_compatible_keys, name) then
       description = description .. " (Picker compatible)"
    end
  end

I don't know if that kind of code would be welcome? Otherwise I can just modify the defaults option description keys individually.

What would be the proper way to indicate a key is "picker compatible"? That is my own terminology but there might be a proper term? How would you prefer I annotate such keys in the defaults description ?

Depending on if there are more compatible keys, or more non-compatible, it may be preferable to rather another when a key is not compatible with pickers (so "Telescope Specific" you may say)

Either have "Picker-compatible" or similar tag on options that pickers can use, or have "Global Only" for options pickers cannot use.

                                          *telescope.defaults.initial_mode*
    initial_mode: ~
        Determines in which mode telescope starts. Valid Keys:
        `insert` and `normal`.

        Picker-compatible
        Default: "insert"

                                      *telescope.defaults.default_mappings*
    default_mappings: ~
        Not recommended to use except for advanced users.

        Will allow you to completely remove all of telescope's default maps
        and use your own.

        Global Only
        Default: nil

Please let me know what changes are welcome or not, and the direction you feel this should go in.

EDIT: I could also try and implement the inheritance definition in the docgen tool if you're okay with it and if you think it's doable with intermediate knowledge of lua and neovim tools