Re: [PATCH] Explain a bit more on how to configure language server in Eglot's manual

[Michael Eliachevitch <m.eliachevitch@posteo.de>]

[-- Attachment #1.1: Type: text/plain, Size: 2510 bytes --]


> Hmmm.  I don't use "pylint" but what sense does it make to disable it
> entirely (supposedly, that's what :enabled :json-false does) and then
> _also_ pass args to it.  Should we just enable it?  This is all pretend,
> of course.  But shouldn't it make more sense?

Ooops. I had simply looked through the available pylsp options [1] seeing which are of array type and would fit into the example plist that we already have. But you're right it doesn't make much sense here [2].

Instead, I would prefer to set some other array option from [1]. There are many more plugin options, but most of them are better set in python project configuration files (including the earlier pylint args), so personally I never use them.

In the now attached patch v3 I set `pylsp.plugins.jedi_completion.cache_for', as we already have a :jedi_completion key (and it's enabled). By default it caches ["pandas", "numpy", "tensorflow", "matplotlib"]. One might want to extend the default list, but to keep the example short I just set it to a subset of the default. What do you think about that?

[1]: See https://github.com/python-lsp/python-lsp-server/blob/develop/CONFIGURATION.md

[2]: When I'm pedantic (:pylint (:enabled :json-false)) also doesn't do anything since pylint is disabled by default, but I see some value in being explicit so I think for an example it's fine.

> "Lisp" should be capitalized (pedantically, "Elisp", since vectors in
> other dialects have different read syntax, but Lisp is fine)

In the patch below I use "Elisp vectors" now.

I would be fine with you editing the patch if you find some minor things to improve or have a better idea for the example. Git commits can have co-authors (this is what github does when you accept suggestions from reviewers), but not sure how the typical workflows are on emacs-devel (I just recently joined to keep up-to-date with recent developments). Or should the patch submitter must aggregate all suggestions into a final patch themselves?

> I'll push the patch soon it with a
>
>   Copyright-paperwork-exempt: Yes
>
> cookie, since this seems to fall under the "trivial" basket, but you
> should probably get a FSF copyright assignment for future contributions.

I'll try that soon. This patch changes just a couple of lines of documentation, so I hope it's fine for now. Slowly I'm figuring out this mailing list workflow and with the copyright assignment, there would be no hurdles for larger contributions to Emacs in the future :)

Michael Eliachevitch


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: v3 of patch for eglot jsonrpc array documentation --]
[-- Type: text/x-patch, Size: 3348 bytes --]

From d7a083c791a8a09db2f6a67603816c92baa9b690 Mon Sep 17 00:00:00 2001
From: Michael Eliachevitch <m.eliachevitch@posteo.de>
Date: Tue, 14 Mar 2023 22:47:37 +0100
Subject: [PATCH v3] Document how to set JSON arrays in
 eglot-workspace-configuration

Many language server configuration options are lists of the JSON array
datatype, for example argument lists for executables. These can be
configured in emacs lisp as vectors. The eglot documentation talked
about confiring json as plists and introduced some basic json
datatypes, but didn't yet mention arrays, which this commit
introduced.

Other changes

* Align property lists in eglot documentation, so that keywords of the
  same level are aligned

* Slightly change punctuation before code example to better
  grammatically integrate the example code and the text.
---
 doc/misc/eglot.texi | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/doc/misc/eglot.texi b/doc/misc/eglot.texi
index 735da5f0163..d3d4337af89 100644
--- a/doc/misc/eglot.texi
+++ b/doc/misc/eglot.texi
@@ -1201,7 +1201,7 @@ User-specific configuration
 The argument @code{(:compilationDatabasePath "/tmp")} is Emacs's
 representation in plist format of a simple JSON object
 @code{@{"compilationDatabasePath": "/tmp"@}}.  To learn how to
-represent more deeply nested options in this format, @xref{JSONRPC
+represent more deeply nested options in this format, @pxref{JSONRPC
 objects in Elisp}.
 
 In this case, the two examples achieve exactly the same, but notice
@@ -1214,7 +1214,7 @@ User-specific configuration
 @code{eglot-workspace-configuration}, a variable originally intended
 for project-specific configuration.  This has the same effect as
 giving all your projects a certain default configuration, as described
-in @xref{Project-specific configuration}.  Here is an example.
+in @ref{Project-specific configuration}.  Here is an example:
 
 @lisp
 (setq-default eglot-workspace-configuration
@@ -1241,17 +1241,21 @@ JSONRPC objects in Elisp
 For representing the JSON leaf values @code{true}, @code{false},
 @code{null} and @code{@{@}}, you can use the Lisp values @code{t},
 @code{:json-false}, @code{nil}, and @code{eglot-@{@}}, respectively.
+JSON arrays are represented as Elisp vectors surrounded by square brackets
+(@pxref{Vectors,,,elisp,GNU Emacs Lisp Reference Manual}).
 
-For example, this plist:
+For example, the plist
 
 @lisp
 (:pylsp (:plugins (:jedi_completion (:include_params t
-                                             :fuzzy t)
-                           :pylint (:enabled :json-false)))
+                                     :fuzzy t
+                                     :cache_for ["pandas" "numpy"]
+                   :pylint (:enabled :json-false))))
  :gopls (:usePlaceholders t))
 @end lisp
 
-Is serialized by Eglot to the following JSON text:
+@noindent
+is serialized by Eglot to the following JSON text:
 
 @example
 @{
@@ -1259,7 +1263,11 @@ JSONRPC objects in Elisp
     "plugins": @{
       "jedi_completion": @{
         "include_params": true,
-        "fuzzy": true
+        "fuzzy": true,
+        "cache_for": [
+          "pandas",
+          "numpy"
+        ],
       @},
       "pylint": @{
         "enabled": false
-- 
2.40.0


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 519 bytes --]