From 10fc11798b9309b8cb6b3aa2bb5d81f2c57cfeb0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ji=C5=99=C3=AD=20Techet?= Date: Mon, 6 May 2024 23:09:15 +0200 Subject: [PATCH] Add documentation --- lsp/README | 266 ++++++++++++++++++++++++++++++++++++++++++++++ lsp/data/lsp.conf | 133 +++++++++++++---------- 2 files changed, 340 insertions(+), 59 deletions(-) diff --git a/lsp/README b/lsp/README index e69de29bb..7586a7e40 100644 --- a/lsp/README +++ b/lsp/README @@ -0,0 +1,266 @@ +=== +LSP +=== + +.. contents:: + +About +===== + +LSP Client is a language server protocol client plugin that allows to run multiple +language servers for various programming languages, making their functionality +accessible to Geany. + +Important limitation +==================== + +The plugin is currently incompatible with Geany's symbol parsing +functionality. This means that in order to make this plugin work correctly, +symbol parsing has to be disabled for all file types for which the plugin +is used. This can be achieved by going to + +:: + + Tools->Configuration Files->...->filetype.some_langguage + +(where ``some_language`` is the language for which symbol +parsing is being disabled) and under the ``[settings]`` section, adding +``tag_parser=`` (no value after ``=``). + +Configuration +============= + +The plugin does not come bundled with any language server; these must +be installed independently of the plugin. For installation and configuration +instructions, please refer to the documentation of the specific servers you plan +to use, as some may have specific requirements. Note that many language servers, +such as ``clangd``, ``pylsp``, and ``gopls``, are often packaged by Linux +distributions, making them easy to install and use. + +By default, no language server is started when the plugin is loaded. +You can configure servers and other settings using the User configuration file, +accessible from:: + + Tools->LSP Client->User configuration + +This file provides extensive information about all the settings options, so be +sure to refer to it for more details. + + +To start a language server for a specific file type, create a section named +``[Filetype]`` (where ``Filetype`` is the name of a language as defined in Geany, +such as ``Python``). Within this section, add the configuration option +``cmd=some_command``, where ``some_command`` is the command to start the server +(for example, ``pylsp`` if the server is on your system's ``PATH``, or the full +path to the server). + +The default configuration file comes with pre-configured values for ``clangd`` +(C, C++), ``pylsp`` (Python), and ``gopls`` (Go). To start these servers, simply +uncomment the ``cmd`` configuration option. + +Language servers are started lazily, meaning they only launch when you switch +a tab to a file with a filetype that has a corresponding LSP server configured. +After the initial handshake between the client and server, you can check the +result under + +:: + + Tools->LSP Client->Server Initialize Responses + +This file also provides information about the capabilities offered by the server; +for more details, refer to: + +https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/ + +In addition to the User configuration file, you can also create a per-project +configuration file or a configuration file shared by multiple projects. This file +can be configured under the + +:: + + Project->Properties->LSP Client + +tab. This tab also provides an option to completely disable LSP for specific +projects. + +Furthermore, the plugin offers a range of customizable keybindings, which can be +configured from:: + + Edit->Preferences->Keybindings->LSP Client + +Usage +===== + +This section provides an overview of the individual LSP features supported by +the plugin, along with guidance on how to use them. You can enable or disable +each feature in the configuration file, where you can also customize certain +aspects of their behavior. + +Please note that not all language servers support every feature. For more +information on the specific features supported by a language server, consult +the server's documentation. + +Autocompletion +-------------- + +Autocompletion works similarly to Geany's autocompletion feature. You can +configure keybindings triggering the autocompletion popup. + +Function signagure +------------------ + +When you type an open brace after a function name, the plugin displays the +function's signature in a popup window similarly to Geany's behavior. + +Diagnostic messages +------------------- + +LSP diagnostic messages typically include error messages or warnings from +compilers, as well as messages from linters. These messages are highlighted in +the code; the exact style of highlighting can be configured to suit your +preferences. When you hover over the highlighted part with your mouse cursor, +a popup window appears, providing additional details about the issue. + +Some servers offer auto-fixes of certain issues. For instance, the ``clangd`` +server displays ``fix available`` next to the issue in the hover popup window. +To perform the auto-fix, right-click the line with the issue and select the +corresponding option from the Commands submenu. + +Code lenses +----------- + +Code lenses are executable commands that are specific to a particular piece of +code. As Geany's Scintilla component limitations prevent these commands +from being clickable and executable directly in the editor, they are accessible +through the Commands submenu of the context menu, similarly to diagnostic +messages. + +Semantic token type highlighting +-------------------------------- + +Language servers that provide semantic token support can be used to highlight +types, such as class names, in the code. You can customize various aspects of +how the results are visualized in the editor through the configuration file. + +Hover popup +----------- + +The language server can be configured to display a popup window with detailed +information about the symbol under the mouse cursor. However, as this feature +can be slightly annoying, it is disabled by default. Alternatively, you can +access this feature through a keybinding. + +Go to symbol definition/declaration +----------------------------------- + +Similarly to Geany, you can navigate to the symbol definition/declaration +by control-clicking it in the document or by using the corresponding keybinding. +This feature is also available from the context menu. + +Go to type definition +--------------------- + +This feature enables quick navigation to the definition of the type associated +with the symbol under the cursor, such as the type of a variable. You can also +access this feature from the context menu. + +Find references +--------------- + +This feature finds all references of the symbol under the cursor in the project. +This feature is also accessible from the context menu. + +Find implementations +-------------------- + +This feature allows you to locate all classes that implement the interface under +the cursor. + +Navigation to document/project symbols, files, and line numbers +--------------------------------------------------------------- + +The plugin provides a simple, VSCode-style panel for navigating your project. +The + +:: + + Tools->LSP Client->Go to Anywhere + +command offers four types of navigation options: + +- Open files by typing their name directly in the entry +- Navigate to symbols in the current document by prefixing the query with ``@`` +- Navigate to symbols across the entire project by prefixing the query with ``#`` +- Jump to a specific line in the current document by prefixing the query with ``:`` + +The other related queries in the LSP Client menu (also accessible via a keybinding) +simply pre-fill the prefix for you, but otherwise function identically. + +Code formatting +--------------- + +The code formatting feature allows you to format either the entire document or +a selected portion of code, depending on the LSP server's support for this +functionality. You can access this feature from the context menu. + +Identical symbol highlighting +----------------------------- + +When you click on a symbol in the document, this feature highlights all its +occurrences in the document. You can customize the highlighting style to your +preference by configuring it in the configuration file. + +Document symbol renaming +------------------------ + +This feature leverages the identical symbol highlighting described above to +select all symbol occurrences, create multiple cursors at their positions in the +document, and rename them simultaneously as you type. You can also access this +feature from the context menu. + +Project-wide renaming +--------------------- + +After selecting Rename in Project from the context menu or the plugin menu, +you can rename all symbols in the project. + +**Warning:** This feature has a potential to modify many files and language +servers may not be completely reliable when performing the rename so be very +cautious when using it. The plugin does not perform any additional +checks and does not show any preview of the changes so it is best to use this +feature only after committing all modified files so you can +easily revert to a working state if needed. + +License +======= + +Geany LSP Client is distributed under the terms of the GNU General Public License +as published by the Free Software Foundation; either version 2 of the +License, or (at your option) any later version. A copy of this license +can be found in the file COPYING included with the source code of this +program. + +Downloads +========= + +Geany LSP Client is part of the combined Geany Plugins release. +For more information and downloads, please visit +https://plugins.geany.org/geany-plugins/ + +Development Code +================ + +Get the code from:: + + git clone https://github.com/geany/geany-plugins.git + +Ideas, questions, patches and bug reports +========================================= + +Please direct all questions, bug reports and patches to the combined geany-plugins +project at https://github.com/geany/geany-plugins and open the corresponding +bug report or pull request there. To notify the author of this plugin about +your post, mention him using his github user name (@techee). + +2023-2024 by Jiří Techet +techet(at)gmail(dot)com diff --git a/lsp/data/lsp.conf b/lsp/data/lsp.conf index 0ac92345e..3085a7523 100644 --- a/lsp/data/lsp.conf +++ b/lsp/data/lsp.conf @@ -1,30 +1,34 @@ -# The global configuration file, accessible through Tools->LSP Client->Global Configuration, -# defines default values for various configuration options. +# The global configuration file, accessible through +# Tools->LSP Client->Global Configuration, defines default values for various +# configuration options. # -# When accessing the user configuration file using Tools->LSP Client->User Configuration, -# a copy of the global configuration file is created in user's configuration directory -# in which one can override various settings from the global configuration file. +# When accessing the user configuration file using +# Tools->LSP Client->User Configuration, a copy of the global configuration file +# is created in user's configuration directory in which users can override +# various settings from the global configuration file. # -# In addition, one can create a project-wide configuration file used for a single -# project or shared by multiple projects whose path can be specified under -# Project->Properties->LSP Client->Configuration file. When such a file is defined -# and the project is configured to use the project configuration, this configuration -# file overrides the global configuration instead of the user configuration file. +# In addition, it is possible to create a project-wide configuration file used +# for a single project or shared by multiple projects whose path can be +# specified under Project->Properties->LSP Client->Configuration file. When such +# a file is defined and the project is configured to use the project +# configuration, this configuration file overrides the global configuration +# instead of the user configuration file. # # Each configuration file may contain the [all] section which contains settings # common for all language servers, and several filetype-specific sections -# containing settings specific for the given filetype. The names of these sections -# are identical to the names defined in Tools->Configuration Files->filetype_extensions.conf; -# for instance [Python] for the Python programming language (case sensitive). -# Most of the options can appear both in the [all] section and the filetype-specific -# sections except for a few that make only sense in the filetype-specific section, -# like e.g. the 'cmd' option containing the command that starts the server. Any -# option defined in the filetype-specific section overrides the option defined -# in the [all] section for that particular language server. +# containing settings specific for the given filetype. The names of these +# sections are identical to the names defined in +# Tools->Configuration Files->filetype_extensions.conf; for instance [Python] +# for the Python programming language (case sensitive). Most of the options can +# appear both in the [all] section and the filetype-specific sections except for +# a few that make only sense in the filetype-specific section, like e.g. the +# 'cmd' option containing the command that starts the server. Any option defined +# in the filetype-specific section overrides identically named option defined in +# the [all] section for that particular language server. # -# Not all LSP features are supported by all LSP servers. To learn more about what -# features are supported by the particular server you are trying, you can check -# the result of the initial client-server handshake by going to +# Not all LSP features are supported by all LSP servers. To learn more about +# what features are supported by the particular server you are trying to use, +# you can check the result of the initial client-server handshake by going to # Tools->LSP Client->Server Initialize Responses (the server must be running # to see any result). # @@ -44,8 +48,8 @@ use_without_project=false # the project directory use_outside_project_dir=false -# When the filetype-specific 'rpc_log' settings is defined (see the Python section), -# this option specifies whether the log should contain all details including method +# When the filetype-specific 'rpc_log' settings is defined, this option +# specifies whether the log should contain all details including method # parameters, or just the method name and type of the communication rpc_log_full=false # Show server's stderr in Geany's stderr (when started from terminal) @@ -53,9 +57,9 @@ show_server_stderr=false # Whether LSP should be used for autocompletion autocomplete_enable=true -# Servers return the label that can be shown in the autocompletion popup for individual -# autocompletion entries, or it is possible to use just the text that gets -# inserted when selecting the entry +# Servers return the label that can be shown in the autocompletion popup for +# individual autocompletion entries, or it is possible to use just the text that +# gets inserted when selecting the entry autocomplete_use_label=false # Maximum number of autocompletion entries shown in the popup window (including # those that will only get visible after scrolling the contents) @@ -66,18 +70,18 @@ autocomplete_window_max_displayed=8 # The maximum width of the autocompletion popup in pixels autocomplete_window_max_width=200 # Whether to automatically apply additional edits defined for the autocompletion -# entry. These are typically imports of the modules where the inserted dymbol is +# entry. These are typically imports of the modules where the inserted symbol is # defined autocomplete_apply_additional_edits=false # Whether LSP should be used to display diagnostic messages. Typically these are # compiler errors or warnings diagnostics_enable=true -# Defines the style of error diagnostics - visual style such as underline, and its -# color. -# The first number is the "indicator index" of Scintilla - each style should have -# a unique value from 8 to 31. Can be changed when the value clashes with some -# other plugin. +# Defines the style of error diagnostics - visual style such as underline, and +# its color. +# The first number is the "indicator index" of Scintilla - each style should +# have a unique value from 8 to 31. Can be changed when the value clashes with +# some other plugin. # The remaining values correspond to # SCI_INDICSETFORE; SCI_INDICSETALPHA; SCI_INDICSETOUTLINEALPHA; SCI_INDICSETSTYLE # - see Scintilla documentation for more information @@ -89,8 +93,8 @@ diagnostics_info_style=15;#909090;70;255;14 # Defines the style of hint diagnostics diagnostics_hint_style=16;#909090;70;255;14 -# Whether LSP should be used to show a popup with details when hovering over symbols. -# Slightly annoying so disabled by default. +# Whether LSP should be used to show a popup with details when hovering over +# symbols. Slightly annoying so disabled by default. hover_enable=false # Maximum number of lines of the popup window hover_popup_max_lines=20 @@ -104,20 +108,21 @@ signature_enable=true # Whether LSP should be used for going to symbol definition/declaration goto_enable=true -# Whether LSP should be used for displaying symbols in the sidebar. At the moment -# there is no Geany support for this feature so it can be left disabled as it does -# not work anyway. +# Whether LSP should be used for displaying symbols in the sidebar. At the +# moment there is no Geany support for this feature so it can be left disabled +# as it does not work anyway. document_symbols_enable=false -# Whether LSP should be used for highlighting semantic tokens in the editor, such -# as types. Most servers don't support this feature so disabled by default. +# Whether LSP should be used for highlighting semantic tokens in the editor, +# such as types. Most servers don't support this feature so disabled by default. semantic_tokens_enable=false -# When commented-out, Scintilla indicators are used for highlighting semantic token types. -# See diagnostics_error_style for more details. +# When uncommented, Scintilla indicators are used for highlighting semantic +# token types. See diagnostics_error_style for more details about the valid +# values. #semantic_tokens_type_style=17;#000090;255;255;17 # When not using semantic_tokens_type_style, this indicates the index in the -# Scintilla lexer used for custom keywords that are used to colorize types. This -# feature is supported only by some lexers like C/C++ and derived lexers. +# Scintilla lexer used for custom keywords. This feature is supported only by +# some lexers like C/C++ and derived lexers. semantic_tokens_lexer_kw_index=3 # Whether LSP should be used for highlighting all other uses of a variable under @@ -126,7 +131,7 @@ highlighting_enable=true # Indicator style used for highlighting - see diagnostics_error_style highlighting_style=18;#b0b0b0;90;255;8 -# Whether LSP should be used for for "code lenses" showing commands available +# Whether LSP should be used for "code lenses" showing commands available # for the given line. After right-clicking the line with the code lens, these # commands are available in the Commands submenu. code_lens_enable=true @@ -137,36 +142,46 @@ code_lens_style=#000000;#ffff00 # This is a dummy language server configuration describing the available # language-specific options [DummyLanguage] -# The command (including parameters) used to start the LSP server. Instead of -# starting a new server, it is also possible to reuse other language's server -# using the 'use' option - see the C++ configuration +# The command (including parameters and possibly also the full path) used to +# start the LSP server. Instead of starting a new server, it is also possible to +# reuse other language's server using the 'use' option - see the C++ +# configuration cmd=srvcmd # The server can be started with additional environment variables (such as foo # with the value bar, and foo1 with the value bar1 like in the example below). env=foo=bar;foo1=bar1 # File containing initialization options of the server. initialization_options_file=/home/some_user/init_options.json -# When defined, performs logging to the specified file where all RPC communication -# between the client plugin and the server will be stored (can also be 'stdout' -# or 'stderr') +# When defined, performs logging to the specified file where all RPC +# communication between the client plugin and the server will be stored (can +# also be 'stdout' or 'stderr') rpc_log=stdout -# Semicolon separated list of character sequences which can trigger autocompletion. -# Normally, the server defines these but this option can be used to further restrict -# the list only to some sequences if the server-provided value does not work well. +# Semicolon separated list of character sequences which can trigger +# autocompletion. Normally, the server defines these but this option can be used +# to further restrict the list only to some sequences if the server-provided +# value does not work well autocomplete_trigger_sequences=.;-> # JSON file containing formatting options defined in # https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#formattingOptions -# containing e.g. { "tabSize": 4, "insertSpaces": false }. Supported only by some -# language servers. +# e.g. { "tabSize": 4, "insertSpaces": false }. Supported only by some language +# servers. formatting_options_file=/home/some_user/my_formatting_config_file.json # Additional files and their mappings to LSP language IDs for which the server # is used as well. The Nth item in the list is always a LSP language ID and the -# (N+1)th item is a glob pattern for which the language ID is used +# (N+1)th item is a glob pattern defining files for which the language ID is +# used lang_id_mappings=dummylanguage;*.dummy [C] -# Comment out the line below to start using the server +# By default, clangd expects compile_commands.json inside the 'build' directory +# of your project. You can create it using either 'meson setup build' if your +# project uses meson or e.g. using: +# mkdir build; bear --output build/compile_commands.json -- make +# if your project uses some other build tool (you need to install the bear tool +# first) +# +# Uncomment the line below to start using the server #cmd=clangd semantic_tokens_enable=true autocomplete_trigger_sequences=.;::;->;->* @@ -183,7 +198,7 @@ use=C [Go] -# Comment out the line below to start using the server +# Uncomment the line below to start using the server #cmd=gopls autocomplete_apply_additional_edits=true lang_id_mappings=go.mod;go.mod;go.sum;go.sum;gotmpl;*tmpl @@ -193,7 +208,7 @@ lang_id_mappings=go.mod;go.mod;go.sum;go.sum;gotmpl;*tmpl [Python] -# Comment out the line below to start using the server +# Uncomment the line below to start using the server #cmd=pylsp use_outside_project_dir=true use_without_project=true