[Feature request] Better document how to customize which text should be visible

[Hubro]

I don't understand how Twilight decides which text should be visible, or how to customize it. I use it with Python + Treesitter, and here's an example of how it works:

I would like it to always expand to include the nearest parent function definition, or the nearest parent class definition if I'm not currently inside a function definition.

It sounds like, based on this:

expand = { -- for treesitter, we we always try to expand to the top-most ancestor with these types
"function",
"method",
"table",
"if_statement",
},

That it already should try to include the entire function definition, but it doesn't. It also sounds like based on this:

context = 10, -- amount of lines we will try to show around the current line

That it should show at least 10 lines above/below the current line, but it doesn't do that either. In the screenshot, it only shows 1 line above the current line.

I would really love some more in-depth documentation so I can customize which text is visible.

[silentjay]

You can install treesitter playground to find the code blocks you want to highlight and add it to the expand list. In your image I assume this means you'd want to add function_definition to expand.

[Hubro]

Hey, that works!

Is there currently any way to specify "expand until the closest parent of one of the following types"?

i.e. expand to either a function definition or class definition, whichever is closer?

So if I'm editing the properties of a class:

class Foo:
    bar: int = 123
    baz: str = "foo"
    # etc.

At this point, I want Twilight to keep the entire class in focus, but if I'm editing a class method, I only want the function definition in focus, not the entire class.