Make documentation more friendly

[danielo515]

First of all, let me say thank you for this amazing tool. I have tried other fuzzy finders before, and none was as easy to use, configure and extend as this one is. It really made me go back to nvim, and that is something that makes me super happy, so thank you very much.

Is your feature request related to a problem? Please describe. My request is about developer/advanced user experience and my relation with the docs, which has not been very nice and a bit frustrating.

Describe the solution you'd like I want the docs to be a bit more structured and easier to navigate. Probably adding more advanced examples will help.

Additional context Here are some of the pain points I found. I think it will be easier to act on things that are clearly defined.

The structure of the first part of the doc is confusing. It starts very good, but then I had to verify several times that I was not skipping parts, because there are several points tha I consider key parts missing. So, this is the beginning:

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,
        --   ...
        -- }
        -- Now the picker_config_key will be applied every time you call this
        -- builtin picker
BLABLA

So far so good, makes sense. Then you start to document the valid keys for the first par of the config, which is great:

   Valid keys for {opts.defaults}

                                      *telescope.defaults.sorting_strategy*
    sorting_strategy: ~

And then, after a lot of text it jumps straight to registering extensions telescope.register_extension. What? Where are all the other options documented? What are the concrete config bits that a picker accepts? From there it then goes to builtin pickers. I think I am supposed to understand that all the options documented inside each builtin.picker_name are also possible to be provided to the initial setup? If that is the case, a single line saying see builtin.picker (or whatever) for configuration options. But even then, no single picker documents an option to define custom mappings, and seems that it is possible to define mappings per picker. I don't even remember where I read that to be honest, but it is true. I think documenting all the options the setup function expects explicitly and before anything else is the best thing for most readers, but I may be mistaken.

Certain options are documented outside the main project

By reading the documentation of telescope-file-browser I discovered that mappings can be functions:

      mappings = {
        ["i"] = {
          -- remap to going to home directory
          ["<C-h>"] = fb_actions.goto_home_dir
          ["<C-x>"] = function(prompt_bufnr)
            -- your custom function
          end
        },

This may be obvious for someone familiar with the plugin and/or lua, but it was a complete surprise to me. Sure, the actions you are supposed to import from 'telescope.actions' are already functions, but unless you dig into the code they could be strings, maps or anything else.

** Advanced options are not documented **

There are, for example, other advanced features that seem to be part of the API that are not documented anywhere. I discovered them reading the recipes wiki, digging through the code and reading discussions on pull requests. I'm talking about, for example, attach_mappings. And since there is no documentation on it nor on how to pass specific mappings per picker is very hard to figure out which is the recommended or official way if there is any. The same happens with transform_mod, which appears on one example on the readme but I was not able to figure out what it does yet.

I still have to check the developers docs, but I was hoping to not have to resort to that since I was not trying to build an extension (YET!) Other than that, the experience has been amazing and the tool is superb, thank you very much for the effort on it and making it that extensible

[Conni2461]

Thanks for the kind words. :)

We decided to do something "experimental" for our documentation, generating it with a custom written tool using a custom tree-sitter grammar see.

So we end up with this problem that stuff come up in code in a specific order and end up in the same order in the documentation. Thats the problem you described with going from telescope.setup documentation to register_extension (which is a developer function). You can see it here: https://github.com/nvim-telescope/telescope.nvim/blob/6e7ee3829225d5c97c1ebfff686050142ffe5867/lua/telescope/init.lua#L75-L90

What we could do is switch the order with load_extension because this one is for users and its pretty important.

I wrote this getting started section to guide users a little bit towards reading the right sections in the right order: https://github.com/nvim-telescope/telescope.nvim/blob/6e7ee3829225d5c97c1ebfff686050142ffe5867/lua/telescope/init.lua#L14-L22

Something that bothers me as well is that you have to do builtin.picker rather than telescope.builtin.picker and is also a limitation of generating because i haven't implemented this prefixing. (yet)

Good point that we forgot to document that you can define custom mappings on builtins. We need to fix that.

Mappings got a small rewrite here: https://github.com/nvim-telescope/telescope.nvim/pull/1473/files#diff-79c55de55b65fbaa2b214c1f3d28277a87a5b6ac9e5e0c87168a3341a471e5d4R1515 that was never merged unfortunately (cant remember why) and is now a nightmare to rebase. But it also misses that actions can be normal functions.

And its a shame that i have not documented transform_mod because its amazing. It turns a table of functions into a table of metatables and then you can do x.a + x.b and the function x.a runs after x.b. It also allows some of the amazing stuff that is documented in developers.md like replace and enhance. See

I guess i'll sit down tomorrow and try to fix some of your criticism. I would also ping you for feedback, if thats allowed :)

[danielo515]

I guess i'll sit down tomorrow and try to fix some of your criticism. I would also ping you for feedback, if thats allowed :)

Of course you can, what kind of person opens an issue complaining and the does not allow to be pinged with the solution? I don't know, all I know is that I am not that person 😁.

That is what happens with in-house solutions, you think the task is going to be simpler and smaller, but there is always an edge case, and you're the only one that can fix it, and it is so time consuming for a "meta-task"... I've been there.

Even if you change the order of the code to better match the user interests about what to read first, I think the entire documentation of what parameters can be passed to the setup function should be in the same place, but if it is referenced and easy to find, I guess that's good enough!

And its a shame that i have not documented transform_mod because its amazing. It turns a table of functions into a table of metatables and then you can do x.a + x.b and the function x.a runs after x.b. It also allows some of the amazing stuff that is documented in developers.md like replace and enhance. See

That looks like a nice way of doing function composition to me 😉. I already read the developer docs and I have to say that are much more user friendly (ironically) than the users documentation, I liked it. How that replace method only for the current execution works is still black magic to my eyes, and that's something I can't live with, will have to investigate it.

Thanks for your prompt and friendly response

[Conni2461]

what parameters can be passed to the setup function

This documentation is part of |telescope.setup| we go over sorting_strategy, tiebreak,selection_strategy, ... In the past this was sorted pretty good but in my option tiebreak needs to come later. I'll reorder this.

developer docs and I have to say that are much more user friendly (ironically) than the users documentation

Thanks. Thats the latest docs me and the team wrote :laughing:

How that replace method only for the current execution works is still black magic to my eyes

Code can be found in lua/telescope/actions/mt.lua

I need to make this into actionable items:

• [x] Update actions docs, and document transform_mod
• [x] Reorder setup values
• [x] Register extenions needs to be swaped with load_extension (or even removed)
• [x] tree-sitter-lua module extension so we can have telescope.builtin.find_files
• [x] mappings docs ! #1473
• [x] attach_mappings not documented (and more of the internal api)
• [ ] ...

[HiPhish]

I just want to chime in to say that gO opens an empty location list for me. It works fine in other manuals, only Telescope is broken. I have run helptags ALL, Telescope topics do get suggested when I tab-complete :help. Maybe it is due to how the documentation is generated.

[Conni2461]

@HiPhish it should be fixed

[HiPhish]

Yes, gO works now in the manual.

[tex]

It would be nice to document fact that you have to first require("telescope").setup({}) and the do load_extension("...")... If not, then configuration of extensions in the setup is ignored...