129 lines
4.4 KiB
Markdown
129 lines
4.4 KiB
Markdown
# fennel-ls external library documentation
|
|
|
|
fennel-ls can load external documentation and completion information for
|
|
situations where it's not available at runtime.
|
|
|
|
## Installing docsets
|
|
|
|
The documentation files (also called docsets) are loaded from
|
|
`~/.local/share/fennel-ls/docsets/` and they are regular Lua files that contain
|
|
a single table describing the information to be displayed by the language
|
|
server.
|
|
|
|
> fennel-ls follows the XDG base directory convention, so if you changed
|
|
> `$XDG_DATA_HOME` the files will be loaded from the location you specified.
|
|
|
|
To install a new docset and make it available to fennel-ls, download the `.lua`
|
|
file for your library and place it in `~/.local/share/fennel-ls/docsets/`.
|
|
|
|
> You can find a list of the available docsets on the [Fennel
|
|
> wiki](http://wiki.fennel-lang.org/LanguageServer).
|
|
|
|
Next, you have to tell fennel-ls to load this library by adding it to the
|
|
`flsproject.fnl` file at the root of your project.
|
|
|
|
```fnl
|
|
{:libraries {:library-name true}}
|
|
```
|
|
|
|
The library name you specify here must match the name of the docset file you
|
|
downloaded.
|
|
|
|
Restart the LSP client or your editor and the new completions should be
|
|
available.
|
|
|
|
## Creating docsets
|
|
|
|
The top level Lua table in the docset should contain symbol names as keys and
|
|
*bindings* as values. These examples use Fennel syntax, so they should
|
|
be compiled to Lua before installation or distribution.
|
|
|
|
```fnl
|
|
{:symbol-a {
|
|
;; binding table
|
|
}
|
|
:symbol-b {
|
|
;; binding table
|
|
}}
|
|
```
|
|
|
|
Each binding is table that describes that symbol. This is an example from the
|
|
Tic-80 library:
|
|
|
|
```fnl
|
|
{:binding "elli"
|
|
:metadata {:fls/itemKind "Function"
|
|
:fnl/arglist ["x" "y" "a" "b" "color"]
|
|
:fnl/docstring "This function draws a filled ellipse of the desired
|
|
a, b radiuses and color with its center at x, y.
|
|
"}}
|
|
```
|
|
|
|
- `binding` is the full name of the symbol, so if this symbol is part of a
|
|
module the name should be in the form `module.symbol`; if it doesn't
|
|
have a dot in it then it's interpreted as a global.
|
|
|
|
- `fls/itemKind` describes the kind of this symbol, it can be any one of the
|
|
[CompletionItemKind](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#completionItemKind)
|
|
values from the LSP specification.
|
|
|
|
- `fnl/arglist` and `fnl/docstring` should follow the usual Fennel conventions.
|
|
|
|
Symbols can also have sub-symbols, represented as fields in the binding
|
|
table. This is an example from the LÖVE library:
|
|
|
|
```fnl
|
|
{:love {:binding "love"
|
|
:metadata {:fls/itemKind "Module"
|
|
:fnl/docstring "Modules can have documentation too"}
|
|
:fields {:conf {:binding "love.conf"
|
|
:metadata {:fls/itemKind "Function"
|
|
:fnl/arglist ["t"]
|
|
:fnl/docstring "Using the love.conf function,
|
|
you can set some configuration options, [...]"}
|
|
```
|
|
|
|
### Complete example
|
|
|
|
Here is a simplified complete example to show all the pieces together, mainly
|
|
the top level table that contains all the bindings.
|
|
|
|
```fnl
|
|
{
|
|
{:math {:binding "math"
|
|
:metadata {:fls/itemKind "Module"
|
|
:fnl/docstring "A module for math functions"}
|
|
:fields {:atan {:binding "math.atan"
|
|
:metadata {:fls/itemKind "Function"
|
|
:fnl/arglist [a]
|
|
:fnl/docstring "Arc tangent"}}
|
|
:phi {:binding "math.phi"
|
|
:metadata {:fls/itemKind "Constant"
|
|
:fnl/docstring "It's golden!"}}}}}
|
|
|
|
{:config {:binding "config"
|
|
:metadata {:fls/itemKind "Function"
|
|
:fnl/arglist []
|
|
:fnl/docstring "A function to read the config options"}}}
|
|
}
|
|
```
|
|
|
|
The easiest way of generating this format is to create the table in a Fennel
|
|
script and then serializing it using the `fennel.view` function.
|
|
|
|
## Compilation
|
|
|
|
Finally, to be usable by fennel-ls the table needs to be compiled to Lua and
|
|
installed in the docsets directory. Consider publishing them over HTTP
|
|
and adding them to [the wiki](http://wiki.fennel-lang.org/LanguageServer)
|
|
if they are likely to be useful to other Fennel developers.
|
|
|
|
```sh
|
|
fennel --compile library-docset.fnl > library-docset.lua
|
|
cp library-docset.lua $HOME/.local/share/fennel-ls/docsets/
|
|
```
|
|
|
|
Refer to the
|
|
[fennel-ls-docsets](http://git.sr.ht/~technomancy/fennel-ls-docsets) repository
|
|
for an example of how to script these steps.
|