branch: elpa/cider
commit 42df588c8da8151ff55f01322c731c7f1980a9ee
Author: Bozhidar Batsov <[email protected]>
Commit: Bozhidar Batsov <[email protected]>
Add screenshots for the 2.0 features to the docs
Real captures of the transient menus (top-level and test), the trace
and tap buffers, the who-calls tree, the namespace browser, a
cider-doctor report and inline macro stepping, produced with a scripted
Emacs against a live nREPL session. Also give the namespace browser a
small section in misc_features, which somehow never had one.
---
doc/modules/ROOT/assets/images/cider-browse-ns.png | Bin 0 -> 160796 bytes
doc/modules/ROOT/assets/images/cider-doctor.png | Bin 0 -> 156012 bytes
.../ROOT/assets/images/cider-macrostep-for-gensyms.png | Bin 0 -> 205806 bytes
.../ROOT/assets/images/cider-macrostep-when-let.png | Bin 0 -> 164915 bytes
doc/modules/ROOT/assets/images/cider-menu.png | Bin 0 -> 224349 bytes
doc/modules/ROOT/assets/images/cider-tap-buffer.png | Bin 0 -> 120791 bytes
doc/modules/ROOT/assets/images/cider-test-menu.png | Bin 0 -> 218418 bytes
doc/modules/ROOT/assets/images/cider-trace-buffer.png | Bin 0 -> 324387 bytes
doc/modules/ROOT/assets/images/cider-who-calls.png | Bin 0 -> 101128 bytes
doc/modules/ROOT/pages/debugging/macroexpansion.adoc | 4 ++++
doc/modules/ROOT/pages/debugging/tap.adoc | 2 ++
doc/modules/ROOT/pages/debugging/tracing.adoc | 2 ++
doc/modules/ROOT/pages/testing/running_tests.adoc | 2 ++
doc/modules/ROOT/pages/troubleshooting.adoc | 2 ++
doc/modules/ROOT/pages/usage/cider_mode.adoc | 2 ++
doc/modules/ROOT/pages/usage/misc_features.adoc | 11 +++++++++++
doc/modules/ROOT/pages/usage/navigation.adoc | 2 ++
17 files changed, 27 insertions(+)
diff --git a/doc/modules/ROOT/assets/images/cider-browse-ns.png
b/doc/modules/ROOT/assets/images/cider-browse-ns.png
new file mode 100644
index 0000000000..df085668ae
Binary files /dev/null and b/doc/modules/ROOT/assets/images/cider-browse-ns.png
differ
diff --git a/doc/modules/ROOT/assets/images/cider-doctor.png
b/doc/modules/ROOT/assets/images/cider-doctor.png
new file mode 100644
index 0000000000..f0d32cd89f
Binary files /dev/null and b/doc/modules/ROOT/assets/images/cider-doctor.png
differ
diff --git a/doc/modules/ROOT/assets/images/cider-macrostep-for-gensyms.png
b/doc/modules/ROOT/assets/images/cider-macrostep-for-gensyms.png
new file mode 100644
index 0000000000..8a17426e26
Binary files /dev/null and
b/doc/modules/ROOT/assets/images/cider-macrostep-for-gensyms.png differ
diff --git a/doc/modules/ROOT/assets/images/cider-macrostep-when-let.png
b/doc/modules/ROOT/assets/images/cider-macrostep-when-let.png
new file mode 100644
index 0000000000..f51913e67b
Binary files /dev/null and
b/doc/modules/ROOT/assets/images/cider-macrostep-when-let.png differ
diff --git a/doc/modules/ROOT/assets/images/cider-menu.png
b/doc/modules/ROOT/assets/images/cider-menu.png
new file mode 100644
index 0000000000..029700741e
Binary files /dev/null and b/doc/modules/ROOT/assets/images/cider-menu.png
differ
diff --git a/doc/modules/ROOT/assets/images/cider-tap-buffer.png
b/doc/modules/ROOT/assets/images/cider-tap-buffer.png
new file mode 100644
index 0000000000..f3394822eb
Binary files /dev/null and
b/doc/modules/ROOT/assets/images/cider-tap-buffer.png differ
diff --git a/doc/modules/ROOT/assets/images/cider-test-menu.png
b/doc/modules/ROOT/assets/images/cider-test-menu.png
new file mode 100644
index 0000000000..50fc5eddd5
Binary files /dev/null and b/doc/modules/ROOT/assets/images/cider-test-menu.png
differ
diff --git a/doc/modules/ROOT/assets/images/cider-trace-buffer.png
b/doc/modules/ROOT/assets/images/cider-trace-buffer.png
new file mode 100644
index 0000000000..8909574771
Binary files /dev/null and
b/doc/modules/ROOT/assets/images/cider-trace-buffer.png differ
diff --git a/doc/modules/ROOT/assets/images/cider-who-calls.png
b/doc/modules/ROOT/assets/images/cider-who-calls.png
new file mode 100644
index 0000000000..deaeac56f0
Binary files /dev/null and b/doc/modules/ROOT/assets/images/cider-who-calls.png
differ
diff --git a/doc/modules/ROOT/pages/debugging/macroexpansion.adoc
b/doc/modules/ROOT/pages/debugging/macroexpansion.adoc
index c38f126415..e1dd0e9d9f 100644
--- a/doc/modules/ROOT/pages/debugging/macroexpansion.adoc
+++ b/doc/modules/ROOT/pages/debugging/macroexpansion.adoc
@@ -192,6 +192,8 @@ kbd:[p]
| Collapse every expansion and leave `cider-macrostep-mode`.
|===
+image::cider-macrostep-when-let.png[cider-macrostep expanding when-let inline]
+
Each expansion remembers the exact text it replaced, so collapsing restores the
original verbatim and nested expansions peel back in order. The operators of
sub-forms that can be expanded further (those that resolve to a macro) are
@@ -199,6 +201,8 @@ underlined so you can see what's left to expand, and
kbd:[n]/kbd:[p] jump
between them. The gensyms a macro introduces (e.g. `x__42__auto__`) are each
given their own color, so a binding can be tracked through the expansion.
+image::cider-macrostep-for-gensyms.png[cider-macrostep expanding for, with
colorized gensyms]
+
NOTE: The expandable-head highlighting and gensym coloring rely on the
`cider/classify-symbols` nREPL op, available in cider-nrepl 0.60 and newer.
Without it the stepping still works, just without those visual aids.
diff --git a/doc/modules/ROOT/pages/debugging/tap.adoc
b/doc/modules/ROOT/pages/debugging/tap.adoc
index 3830e87935..c4baff00a0 100644
--- a/doc/modules/ROOT/pages/debugging/tap.adoc
+++ b/doc/modules/ROOT/pages/debugging/tap.adoc
@@ -10,6 +10,8 @@ Any `+(tap> some-value)+` in your code shows up in that
buffer as it happens, as
does anything you tap from the xref:inspector.adoc[inspector]. The buffer
follows
the tail, so the newest value is always in view.
+image::cider-tap-buffer.png[The cider-tap buffer streaming tapped values]
+
NOTE: This requires a recent enough `cider-nrepl` (the one that ships the `tap`
middleware). Without it the command won't have anything to subscribe to.
diff --git a/doc/modules/ROOT/pages/debugging/tracing.adoc
b/doc/modules/ROOT/pages/debugging/tracing.adoc
index 804bbde538..8e846066f3 100644
--- a/doc/modules/ROOT/pages/debugging/tracing.adoc
+++ b/doc/modules/ROOT/pages/debugging/tracing.adoc
@@ -23,6 +23,8 @@ By default the trace output lands in the REPL, mixed in with
everything else.
functions, call them, and their calls and return values stream into that buffer
live, indented to show the call nesting. Kill the buffer to stop streaming.
+image::cider-trace-buffer.png[The cider-trace buffer with a nested call tree]
+
Inside the buffer:
* kbd:[TAB] (or a click) on a call line folds or unfolds the nested calls
between
diff --git a/doc/modules/ROOT/pages/testing/running_tests.adoc
b/doc/modules/ROOT/pages/testing/running_tests.adoc
index 429732b59d..60c9e2d8e8 100644
--- a/doc/modules/ROOT/pages/testing/running_tests.adoc
+++ b/doc/modules/ROOT/pages/testing/running_tests.adoc
@@ -172,6 +172,8 @@ commands dispatched through the menu; the plain keybindings
and the
`cider-test-default-include-selectors`/`cider-test-default-exclude-selectors`
variables are untouched.
+image::cider-test-menu.png[The test transient menu with selector flags]
+
=== Display Test Report on Success
By default the test report is displayed only when there are test failures or
diff --git a/doc/modules/ROOT/pages/troubleshooting.adoc
b/doc/modules/ROOT/pages/troubleshooting.adoc
index 79a82ed61f..fb8c998010 100644
--- a/doc/modules/ROOT/pages/troubleshooting.adoc
+++ b/doc/modules/ROOT/pages/troubleshooting.adoc
@@ -26,6 +26,8 @@ nREPL, `cider-nrepl` and Clojure versions and probes the
middleware ops
that back the major features - so a missing feature shows up as a named
missing op rather than a mystery.
+image::cider-doctor.png[A cider-doctor report]
+
Press kbd:[g] in the report buffer to re-run the checks in place, for
instance after installing a missing dependency or starting a REPL.
diff --git a/doc/modules/ROOT/pages/usage/cider_mode.adoc
b/doc/modules/ROOT/pages/usage/cider_mode.adoc
index 437ca8d9c4..effe86c56b 100644
--- a/doc/modules/ROOT/pages/usage/cider_mode.adoc
+++ b/doc/modules/ROOT/pages/usage/cider_mode.adoc
@@ -95,6 +95,8 @@ kbd:[C-c C-d C-d] runs `cider-doc` immediately; the menu only
appears if you
*pause* after the prefix. There's also a top-level `cider-menu` command (not
bound by default) that dispatches into all of the group menus, magit-style.
+image::cider-menu.png[The top-level cider-menu transient]
+
Some menus also offer *arguments* (toggled with kbd:[-] keys, magit-style)
that tweak the commands for a single invocation, without touching your saved
configuration:
diff --git a/doc/modules/ROOT/pages/usage/misc_features.adoc
b/doc/modules/ROOT/pages/usage/misc_features.adoc
index d25359ecd3..f68180eaaa 100644
--- a/doc/modules/ROOT/pages/usage/misc_features.adoc
+++ b/doc/modules/ROOT/pages/usage/misc_features.adoc
@@ -48,6 +48,17 @@ buffer, not just the scratchpad - they are handy in `.cljc`
buffers too, when
you want to pin evaluations to a specific REPL instead of the
`cider-clojurec-eval-destination` default.
+== Browsing Namespaces
+
+kbd:[M-x] `cider-browse-ns` displays the vars of a namespace (defaulting to
+the current one) in a browsable buffer, along with the first sentence of each
+var's docstring; `cider-browse-ns-all` lists all loaded namespaces instead.
+The entries can be grouped (by type or visibility) and filtered from the
+header, groups fold with kbd:[TAB], kbd:[n]/kbd:[p] move between entries, and
+kbd:[RET] (or kbd:[.]) visits the definition of the var at point.
+
+image::cider-browse-ns.png[The namespace browser]
+
== Browsing the Clojure Spec Registry
If you already know which spec you're looking for, you can type
diff --git a/doc/modules/ROOT/pages/usage/navigation.adoc
b/doc/modules/ROOT/pages/usage/navigation.adoc
index d426a842ea..04bdab7bed 100644
--- a/doc/modules/ROOT/pages/usage/navigation.adoc
+++ b/doc/modules/ROOT/pages/usage/navigation.adoc
@@ -110,6 +110,8 @@ kbd:[n] and kbd:[p] move between nodes, kbd:[RET] (or
kbd:[.]) jumps to a node's
definition, and a function that calls back onto its own path is shown as a leaf
so expansion can't loop forever.
+image::cider-who-calls.png[The cider-who-calls tree expanded three levels]
+
[NOTE]
====
Like the flat `cider-xref-fn-refs`, these browsers are powered by the runtime
