From 1f123c6baacd057801c6616ff834602b28ea7d8c Mon Sep 17 00:00:00 2001 From: Michele Campeotto Date: Fri, 28 Feb 2025 23:46:50 +0100 Subject: [PATCH] Add docsets information and some reorg --- docs/docsets.md | 124 +++++++++++++++++++++++++++++++++++ docs/installation.md | 116 +++++++++++++++++++++++++++++++++ docs/manual.md | 152 +++++++++++++------------------------------ 3 files changed, 286 insertions(+), 106 deletions(-) create mode 100644 docs/docsets.md create mode 100644 docs/installation.md diff --git a/docs/docsets.md b/docs/docsets.md new file mode 100644 index 0000000..5fb1448 --- /dev/null +++ b/docs/docsets.md @@ -0,0 +1,124 @@ +# 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. + +```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` + +- `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. + +```sh +fennel 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. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..825ad17 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,116 @@ +# Installation + +## Manual installation + +To install from source on Linux or macOS, run: + +```sh +$ git clone https://git.sr.ht/~xerool/fennel-ls +$ cd fennel-ls +$ make docs-love2d # if you plan to use love2d +$ make +``` + +The only dependency is a Lua installation. + +This build will create a `fennel-ls` executable for you using your default +system `lua`; use `make LUA=luajit` etc to use a different Lua version. + +Run `make install PREFIX=$HOME` to put it in `~/bin` or `sudo make install` for +a system wide install. + +The default build will not include documentation for [LÖVE](https://love2d.org) +due to the unfortunate licensing of their documentation. You can opt-in to +build with these docs anyway with `make docs-love2d` but the resulting build +may have legal complications when distributed. + +## Packages + +#### Arch Linux + +I think `fennel-ls` and `fennel-ls-git` may be in the AUR. + +#### NixOS + +If you are using NixOS, you can use the included `/flake.nix` or +`/default.nix`. + +#### Debian/Ubuntu + +Unofficial `.deb` packages are available at +[https://apt.technomancy.us](https://apt.technomancy.us). + +#### Luarocks + +Alternatively, `fennel-ls` is available in LuaRocks, but recommendation is to +use one of the other packaging solutions over LuaRocks, if available. + +```sh +luarocks install fennel-ls +``` + +## Editor integration + +The following instructions assume you have installed `fennel-ls` as described +in the previous section. + +### Emacs + +On Emacs 30+, eglot will use fennel-ls automatically if it can be found in your `$PATH`. + +For older versions: + +```lisp +(with-eval-after-load 'eglot + (add-to-list 'eglot-server-programs '(fennel-mode . ("fennel-ls")))) +``` + +This code tells eglot to connect fennel-ls to your fennel-mode buffers. + +### Neovim + +If you're using neovim+lspconfig, use this snippet: +```lua +require("lspconfig").fennel_ls.setup({}) +``` + +If you're also using mason and you want to install fennel-ls that way, you can +use mason-lspconfig to ensure fennel-ls is installed: +```lua +require("mason-lspconfig").setup { + ensure_installed = {"fennel_ls"} +} +``` + +### Sublime Text + +Install the the [LSP +package](https://packagecontrol.io/packages/LSP) from Package Control. + +You can configure the LSP plugin to use fennel-ls directly by editing your +`Packages/User/LSP.sublime-settings` file, which can be opened via "Preferences +\> Package Settings \> LSP \> Settings" from the menu or with the Preferences: LSP +Settings command from the Command Palette. + +You should add an entry to the top-level `"clients"` object (creating it if it +doesn't exist), with this configuration: +```json +"clients": { + "fennel-ls": { + "enabled": true, + "selector": "source.fennel", + "command": ["fennel-ls"] + } +} +``` + +If you run into problems, check the [LSP Client Configuration +reference](https://lsp.sublimetext.io/client_configuration/) and double-check +the location of fennel-ls on the $PATH is visible to Sublime Text. + +### Other editors + +It should be possible to set up for other text editors, but the instructions +depend on which editor you use. Generally you need to tell your editor: +* "fennel-ls" is a language server program on the $PATH +* it should be run for fennel files. diff --git a/docs/manual.md b/docs/manual.md index 246505b..26e1bbb 100644 --- a/docs/manual.md +++ b/docs/manual.md @@ -1,128 +1,67 @@ # Manual -This document goes over how to set up fennel-ls. - -## Installation - -### fennel-ls Language Server Binary - -On Linux or Mac OS, -```sh -$ git clone https://git.sr.ht/~xerool/fennel-ls -$ cd fennel-ls -$ make docs-love2d # if you plan to use love2d -$ make -``` - -will create a `fennel-ls` executable for you using your default system `lua`; -use `make LUA=luajit` etc to use a different Lua version. - -Run `make install PREFIX=$HOME` to put it in `~/bin` or `sudo make install` for -a systemwide install. - -The default build will not include documentation for [LÖVE](https://love2d.org) -due to the unfortunate licensing of their documentation. You can opt-in to -build with these docs anyway with `make docs-love2d` but the resulting build -may have legal complications when distributed. - -#### Arch Linux -I think `fennel-ls` and `fennel-ls-git` may be in the AUR. - -#### NixOS -If you are using NixOS, you can use the included `/flake.nix` or `/default.nix`. - -#### Debian/Ubuntu - -Unofficial `.deb` packages are available at -[https://apt.technomancy.us](https://apt.technomancy.us). - -#### Luarocks -Alternatively, `fennel-ls` is available in LuaRocks. Luarocks is kind of a pain to support though. -```sh -luarocks install fennel-ls -``` - -### Emacs -prerequisites: You have installed the [fennel-ls binary](#fennel-ls-language-server-binary). - -For Emacs 30+, eglot will use fennel-ls automatically if its on the $PATH. -For older versions: -```lisp -(with-eval-after-load 'eglot - (add-to-list 'eglot-server-programs '(fennel-mode . ("fennel-ls")))) -``` -This code tells eglot to connect fennel-ls to your fennel-mode buffers. - -### Neovim -prerequisites: You have installed the [fennel-ls binary](#fennel-ls-language-server-binary). -If you're using neovim+lspconfig, use this snippet: -```lua -require("lspconfig").fennel_ls.setup({}) -``` - -If you're also using mason and you want to install fennel-ls that way, you can -use mason-lspconfig to ensure fennel-ls is installed: -```lua -require("mason-lspconfig").setup { - ensure_installed = {"fennel_ls"} -} -``` - -### Sublime Text -prerequisites: You have installed the [fennel-ls binary](#fennel-ls-language-server-binary) and the [LSP Sublime Text package](https://packagecontrol.io/packages/LSP) from Package Control. - -You can configure the LSP plugin to use fennel-ls directly by editing your `Packages/User/LSP.sublime-settings` file, which can be opened via "Preferences > Package Settings > LSP > Settings" from the menu or with the Preferences: LSP Settings command from the Command Palette. - -You should add an entry to the top-level `"clients"` object (creating it if it doesn't exist), with this configuration: -```json -"clients": { - "fennel-ls": { - "enabled": true, - "selector": "source.fennel", - "command": ["fennel-ls"] - } -} -``` - -If you run into problems, check the [LSP Client Configuration reference](https://lsp.sublimetext.io/client_configuration/) and double-check the location of fennel-ls on the $PATH is visible to Sublime Text. - -### Other editors -It should be possible to set up for other text editors, but the instructions -depend on which editor you use. Generally you need to tell your editor: -* "fennel-ls" is a language server program on the $PATH -* it should be run for fennel files. +This document has information on how to configure and use fennel-ls after you [installed it](installation.md). ## Configuration -fennel-ls can be configured by creating a file named `flsproject.fnl` in your -workspace root. Any setting that isn't provided will be filled in with the -defaults, which means that `{}` is a valid configuration with default settings. -You can provide different settings in the same shape as the default settings to -override the defaults. -The default `flsproject.fnl` settings are: +fennel-ls can be configured by creating a file named `flsproject.fnl` in the +root of your project. + +The default settings are below, you only need to provide the settings you want +to change. An empty table `{}` is a valid configuration and serves as a marker +to indicate where the project root is located. ```fnl {:fennel-path "./?.fnl;./?/init.fnl;src/?.fnl;src/?/init.fnl" :macro-path "./?.fnl;./?/init-macros.fnl;./?/init.fnl;src/?.fnl;src/?/init-macros.fnl;src/?/init.fnl" :lua-version "lua5.4" - :libraries {:love2d false ; requires building with love2d support - :tic-80 false} + :libraries {} :extra-globals "" :lints {:unused-definition true :unknown-module-field true :unnecessary-method true + :unnecessary-tset true + :unnecessary-do true + :redundant-do true + :match-should-case true :bad-unpack true :var-never-set true :op-with-no-arguments true - :multival-in-middle-of-call true}} + :multival-in-middle-of-call true + :no-decreasing-comparison false} ``` -extra-globals: Space separated list of allowed global identifiers; in addition to a set of predefined lua globals. +- `extra-globals`: Space separated list of allowed global identifiers that will + be added to a set of predefined lua globals. -version: One of lua51, lua52, lua53, lua54, intersection, or union. + These identifiers and any of their fields will be considered valid and won't + produce diagnostics. Use this when importing a library for which + documentation is not available. -libraries: This setting controls which extra documentation fennel-ls can load in to your environment. I've only done this for tic-80 for now. +- `version`: One of `lua5.1`, `lua5.2`, `lua5.3`, `lua5.4`, `intersection`, or + `union`. + `intersection` represents the APIs that are available in *every* supported + Lua version, `union` represents APIs available in *any* version. + +- `libraries`: This setting controls which extra documentation fennel-ls will + load in your environment. Each entry in the table is the name of the library + and a boolean, `true` to enable the library and `false` to disable it. + + The name of the library is the name of a file that will be loaded from + `~/.local/share/fennel-ls/docsets/` after appending the `.lua` extension. + + For example, if the table contains `{:love2d true}` the file `love2s.lua` + will be loaded from `~/.local/share/fennel-ls/docsets/`. + + The available docsets are listed on the [Fennel + wiki](http://wiki.fennel-lang.org/LanguageServer). + + See the full [docsets documentation](docsets.md) for more information on how + to find, install, or create docsets. + + > fennel-ls respects the XDG convention, so if you changed `$XDG_DATA_HOME` + > the files will be loaded from the location you specified. ## Usage @@ -134,7 +73,6 @@ to be macro files. ## Features - Feature | Locals | Fields | Builtin Globals | Across Files | Builtins | Macros | User globals | --------------- | ------ | ------ | --------------- | ------------ | -------- | ------ | ------------ | Completions | [X] | [X] | [X] | [X] | [X] | [X] | [ ] | @@ -155,10 +93,12 @@ purposes, it's recommended to put an underscore at the end. For example: ``` ## CLI Usage + +fennel-ls can be used as a linter from the command line: + ```sh fennel-ls --lint my-file.fnl f2.fnl # prints diagnostics for the files given ``` -This will analyze the given files, and print out all compiler errors and lints, +This will analyze the given files and print out all compiler errors and lints, without launching a server. A successful exit code indicates no problems found. -