[nongnu] elpa/cider dea866c0d8 3/3: Refine shadow-cljs documentation (#3360)

[ELPA Syncer]

branch: elpa/cider
commit dea866c0d8911bf1b13c11d727aba30b7e0a9831
Author: vemv <vemv@users.noreply.github.com>
Commit: GitHub <noreply@github.com>

    Refine shadow-cljs documentation (#3360)
---
 .../ROOT/pages/basics/middleware_setup.adoc        |  2 +-
 doc/modules/ROOT/pages/cljs/figwheel.adoc          |  4 ++--
 doc/modules/ROOT/pages/cljs/other_repls.adoc       |  2 +-
 doc/modules/ROOT/pages/cljs/overview.adoc          |  6 ++++--
 doc/modules/ROOT/pages/cljs/shadow-cljs.adoc       | 23 ++++++++++++++--------
 doc/modules/ROOT/pages/cljs/up_and_running.adoc    |  2 +-
 6 files changed, 24 insertions(+), 15 deletions(-)

diff --git a/doc/modules/ROOT/pages/basics/middleware_setup.adoc 
b/doc/modules/ROOT/pages/basics/middleware_setup.adoc
index df9e54b9f2..da2fe9aec7 100644
--- a/doc/modules/ROOT/pages/basics/middleware_setup.adoc
+++ b/doc/modules/ROOT/pages/basics/middleware_setup.adoc
@@ -89,7 +89,7 @@ run `cider-connect` or `cider-connect-cljs`.
 
   :cider-cljs {:extra-deps {org.clojure/clojurescript {:mvn/version "1.10.339"}
                             cider/cider-nrepl {:mvn/version "0.22.4"}
-                            cider/piggieback {:mvn/version "0.5.1"}}
+                            cider/piggieback {:mvn/version "0.5.3"}}
                :main-opts ["-m" "nrepl.cmdline" "--middleware"
                            
"[cider.nrepl/cider-middleware,cider.piggieback/wrap-cljs-repl]"]}
 ----
diff --git a/doc/modules/ROOT/pages/cljs/figwheel.adoc 
b/doc/modules/ROOT/pages/cljs/figwheel.adoc
index ba56459a8c..46050a8983 100644
--- a/doc/modules/ROOT/pages/cljs/figwheel.adoc
+++ b/doc/modules/ROOT/pages/cljs/figwheel.adoc
@@ -25,7 +25,7 @@ You'll also have to configure Piggieback manually if you're 
planning to use
 +
 [source,clojure]
 ----
-[cider/piggieback "0.5.1"]
+[cider/piggieback "0.5.3"]
 ----
 +
 . Add this to your dev `:repl-options` (not needed for `cider-jack-in-cljs`):
@@ -123,7 +123,7 @@ in the root of your Leiningen project definition.
 +
 [source,clojure]
 ----
-[cider/piggieback "0.5.1"] ; not needed for cider-jack-in-cljs
+[cider/piggieback "0.5.3"] ; not needed for cider-jack-in-cljs
 [figwheel-sidecar "0.5.19"] ; use here whatever the current version of 
figwheel is
 ----
 +
diff --git a/doc/modules/ROOT/pages/cljs/other_repls.adoc 
b/doc/modules/ROOT/pages/cljs/other_repls.adoc
index 43ae210312..010a922f47 100644
--- a/doc/modules/ROOT/pages/cljs/other_repls.adoc
+++ b/doc/modules/ROOT/pages/cljs/other_repls.adoc
@@ -61,7 +61,7 @@ Internally, it's powered by Weasel. Let's go over the steps 
required to use it.
 [adzerk/boot-cljs-repl   "X.Y.Z"  :scope "test"]
 [pandeiro/boot-http      "X.Y.Z"  :scope "test"]
 [weasel                  "0.7.1"  :scope "test"]
-[cider/piggieback "0.5.1"  :scope "test"] ; not needed for cider-jack-in-cljs
+[cider/piggieback "0.5.3"  :scope "test"] ; not needed for cider-jack-in-cljs
 ----
 +
 and this at the end of `build.boot`:
diff --git a/doc/modules/ROOT/pages/cljs/overview.adoc 
b/doc/modules/ROOT/pages/cljs/overview.adoc
index a81cc29096..19a4be7557 100644
--- a/doc/modules/ROOT/pages/cljs/overview.adoc
+++ b/doc/modules/ROOT/pages/cljs/overview.adoc
@@ -17,7 +17,7 @@ and how to setup the most popular ClojureScript REPLs.
 == nREPL and ClojureScript
 
 nREPL doesn't natively support ClojureScript evaluation, that why an additional
-middleware is needed. CIDER relies on the popular Piggieback middleware for its
+middleware is needed. For most REPLs (with the notable exceptions of 
`shadow-cljs`, `nbb`), CIDER relies on the popular Piggieback middleware for its
 ClojureScript support.
 
 Piggieback works in the following manner:
@@ -32,7 +32,9 @@ On the bright side - this also means that you can host side 
by side Clojure and
 REPLs in a single nREPL connection! This opens up all sorts of interesting 
possibilities
 that we'll discuss later on.
 
-== Differences with the Standard ClojureScript REPL
+NOTE: `shadow-cljs`'s REPL is implemented in a very similar fashion, but its 
mechanism is provided by its own nREPL middleware - not Piggieback.
+
+== Piggieback differences with the Standard ClojureScript REPL
 
 While the Piggieback-powered ClojureScript REPLs behave more or less
 the same as the standard ClojureScript REPL, there are few subtle
diff --git a/doc/modules/ROOT/pages/cljs/shadow-cljs.adoc 
b/doc/modules/ROOT/pages/cljs/shadow-cljs.adoc
index 4e487fb87b..64bf7b214d 100644
--- a/doc/modules/ROOT/pages/cljs/shadow-cljs.adoc
+++ b/doc/modules/ROOT/pages/cljs/shadow-cljs.adoc
@@ -54,15 +54,26 @@ Alternatively you can start the server manually with 
something like:
 
 [source,sh]
 ----
-$ npx shadow-cljs server
+$ shadow-cljs watch app
 ----
 
 And connect to it with `cider-connect`.
 
+...For that to work, `shadow-cljs.edn` contents like the following are assumed:
+
+```clj
+ :dependencies [[cider/cider-nrepl "0.31.0"] ;; mandatory (unless it's 
inherited from deps.edn or otherwise present in the classpath of shadow-cljs's 
JVM process)
+                [refactor-nrepl/refactor-nrepl "3.6.0"]] ;; refactor-nrepl is 
optional
+
+ :nrepl {:middleware [cider.nrepl/cider-middleware ;; it's advisable to 
explicitly add this middleware. It's automatically added by shadow-cljs (if 
available in the classpath), unless `:nrepl {:cider false}`
+                      refactor-nrepl.middleware/wrap-refactor] ;; 
refactor-nrepl is optional
+         :port 50655} ;; optional - if not specified, a random free port will 
be used
+```
+
 NOTE: If https://docs.cider.mx/cider-nrepl/[cider-nrepl] isn't in your
-classpath you should make sure it's there. You can do this by adding
-it to `:dependencies` in the `shadow-cljs.edn` configuration file
-residing in the root of your project. Alternatively you can set
+classpath you should make sure it's there. You can do this by correctly filling
+the `shadow-cljs.edn` configuration file
+residing in the root of your project, as described above. Alternatively you 
can set
 `cider-repl-auto-detect-type` to `nil`, as the auto-detection of
 REPL types doesn't work without `cider-nrepl`.
 
@@ -139,7 +150,3 @@ Here are a few useful sections from ``shadow-cljs``'s own 
documentation:
 * 
https://shadow-cljs.github.io/docs/UsersGuide.html#_installation[Installation]
 * https://shadow-cljs.github.io/docs/UsersGuide.html#nREPL[nREPL Setup]
 * https://shadow-cljs.github.io/docs/UsersGuide.html#cider[Integration with 
CIDER]
-
-=== Tutorials
-
-* https://cestlaz.github.io/post/using-emacs-63-clojurescript/[Using 
shadow-cljs with CIDER]
diff --git a/doc/modules/ROOT/pages/cljs/up_and_running.adoc 
b/doc/modules/ROOT/pages/cljs/up_and_running.adoc
index 2b4345b90e..342e1efdca 100644
--- a/doc/modules/ROOT/pages/cljs/up_and_running.adoc
+++ b/doc/modules/ROOT/pages/cljs/up_and_running.adoc
@@ -25,7 +25,7 @@ project or `deps.edn`):
 [source,clojure]
 ----
 ;; use whatever are the most recent versions here
-[cider/piggieback "0.5.1"]
+[cider/piggieback "0.5.3"]
 [org.clojure/clojure "1.9.0"]
 ----