Add cider-log-show-frameworks command

This command renders the available log frameworks in a buffer. It
shows the log framework name, the website and javadocs urls and the
levels for now.

This is mostly to address @vemv's suggestion to ask the user to run
`(cider-sync-request:log-frameworks)`. I hooked the command up at the
usual places and added it with a small troubleshooting section to the
docs.

We could get even more sophisticated and show the current appenders
and consumers but I need a designer for this. Let's do this at some
other point.

CHANGELOG.md

@@ -3,7 +3,7 @@
 ## master (unreleased)
 
 ### Changes
-
+- [#3753](https://github.com/clojure-emacs/cider/pull/3753) Add `cider-log-show-frameworks` command to show available log frameworks in a buffer.
 - [#3746](https://github.com/clojure-emacs/cider/issues/3746): Bring back `cider` completion style for activating backend-driven completion.
 
 ### Bugs fixed

cider-log.el

@@ -48,6 +48,20 @@ Example values: \"Logback\", \"Timbre\"."
   :safe #'stringp
   :type 'string)
 
+(defcustom cider-log-frameworks-buffer "*cider-log-frameworks*"
+  "The name of the log frameworks popup buffer."
+  :group 'cider
+  :package-version '(cider . "1.17")
+  :safe #'stringp
+  :type 'string)
+
+(defcustom cider-log-auto-select-frameworks-buffer t
+  "Whether to auto-select the log frameworks popup buffer."
+  :group 'cider
+  :package-version '(cider . "1.17")
+  :safe #'booleanp
+  :type 'boolean)
+
 (defcustom cider-log-appender-id "cider-log"
   "The name of the default log appender."
   :group 'cider
@@ -1032,6 +1046,26 @@ the CIDER Inspector and the CIDER stacktrace mode.
 
 ;; Framework actions
 
+(transient-define-suffix cider-log-show-frameworks ()
+  "Show the available log frameworks in a buffer."
+  :description "Show frameworks in a buffer"
+  (interactive)
+  (let ((frameworks (cider-sync-request:log-frameworks)))
+    (with-current-buffer (cider-popup-buffer cider-log-frameworks-buffer
+                                             cider-log-auto-select-frameworks-buffer)
+      (read-only-mode -1)
+      (insert (with-temp-buffer
+                (insert (propertize (cider-propertize "Cider Log Frameworks" 'ns) 'ns t) "\n\n")
+                (dolist (framework frameworks)
+                  (insert (propertize (cider-propertize (cider-log-framework-name framework) 'ns) 'ns t) "\n\n")
+                  (insert (format "  Website ......... %s\n" (cider-log-framework-website-url framework)))
+                  (insert (format "  Javadocs ........ %s\n" (cider-log-framework-javadoc-url framework)))
+                  (insert (format "  Levels .......... %s\n" (string-join (cider-log-framework-level-names framework) ", ")))
+                  (newline))
+                (buffer-string)))
+      (read-only-mode 1)
+      (goto-char (point-min)))))
+
 (transient-define-suffix cider-log-browse-javadocs (framework)
   "Browse the Javadoc of the log FRAMEWORK."
   :description "Browse Java documentation"
@@ -1220,6 +1254,7 @@ the CIDER Inspector and the CIDER stacktrace mode.
 (transient-define-prefix cider-log-framework (framework)
   "Show the Cider log framework menu."
   [["Cider Log Framework\n\nActions:"
+    ("a" cider-log-show-frameworks)
     ("b" cider-log-set-buffer)
     ("j" cider-log-browse-javadocs)
     ("s" cider-log-set-framework)
@@ -1441,6 +1476,7 @@ based on `transient-mode'."
 (transient-define-prefix cider-log (framework appender)
   "Show the Cider log menu."
   [["Framework Actions"
+    ("fa" cider-log-show-frameworks)
     ("fs" cider-log-set-framework)
     ("fb" cider-log-set-buffer)
     ("fj" cider-log-browse-javadocs)

doc/modules/ROOT/pages/debugging/logging.adoc

@@ -49,6 +49,7 @@ Its usage is mostly self-describing, since each command has its keybinding attac
 
 To use CIDER Log Mode, there two main ways to get started:
 
+* `M-x cider-log-show-frameworks`, to see the available logging frameworks. If your logging framework is supported but not shown, see the troubleshooting section.
 * `M-x cider-log-event`, which uses transient-mode and will not immediately show the logs (you should use transient-mode to show the `+*cider-log*+` buffer)
 * `M-x cider-log-show` is a newer function that intends to be an "all-in-one" command, intended for a streamlined experience, which can be useful to get started, or for casual usage.
 ** It doesn't use transient-mode - it aims to do everything in one step
@@ -178,6 +179,10 @@ or Clojure CLI aliases.
 |===
 | Command | Keyboard shortcut | Description
 
+| `cider-log-show-frameworks`
+| kbd:[C-c M-l f a]
+| Show all available log frameworks in a buffer.
+
 | `cider-log-set-framework`
 | kbd:[C-c M-l f s]
 | Select the log framework to use.
@@ -351,3 +356,9 @@ using logical AND condition. The following filters are available:
 | kbd:[-t]
 | Only include log events that were emitted by a thread in the list of `threads`.
 |===
+
+== Troubleshooting
+
+- Make sure the logging library is actually supported by CIDER Log Mode and that it is on your classpath.
+- Try requiring the https://github.com/clojure-emacs/logjam/tree/master/src/logjam/framework[Logjam] namespace of the logging library, e.g. `(require 'logjam.framework.<jul|logback|timbre|> :reload)` and make sure it can be loaded without errors.
+- Timbre and Encore often have to be upgraded in concert, they use "break versioning". It's often useful to have Timbre + Encore at the latest stable version.