branch: elpa/cider
commit d6d16e3da34f74f12285b6216c3f9a64a0501d11
Author: Bozhidar Batsov <bozhi...@batsov.dev>
Commit: Bozhidar Batsov <bozhi...@batsov.dev>
[Docs] Move "code reloading" docs to their own section
---
doc/modules/ROOT/nav.adoc | 1 +
doc/modules/ROOT/pages/usage/code_reloading.adoc | 116 +++++++++++++++++++++++
doc/modules/ROOT/pages/usage/misc_features.adoc | 97 -------------------
3 files changed, 117 insertions(+), 97 deletions(-)
diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc
index 121efcc789..06035fd885 100644
--- a/doc/modules/ROOT/nav.adoc
+++ b/doc/modules/ROOT/nav.adoc
@@ -20,6 +20,7 @@
** xref:usage/cider_mode.adoc[Using cider-mode]
** xref:usage/code_evaluation.adoc[Code Evaluation]
** xref:usage/code_completion.adoc[Code Completion]
+** xref:usage/code_reloading.adoc[Code Reloading]
** xref:usage/pretty_printing.adoc[Pretty Printing]
** xref:usage/dealing_with_errors.adoc[Dealing with Errors]
** xref:usage/working_with_documentation.adoc[Working with Documentation]
diff --git a/doc/modules/ROOT/pages/usage/code_reloading.adoc
b/doc/modules/ROOT/pages/usage/code_reloading.adoc
new file mode 100644
index 0000000000..4be5f5b7b0
--- /dev/null
+++ b/doc/modules/ROOT/pages/usage/code_reloading.adoc
@@ -0,0 +1,116 @@
+= Code Reloading
+
+While Clojure's and CIDER's interactive programming style means you'll
+restart your application far less often than with other languages and
+development environments, sometimes you'll want to clean everything up
+and reload one or more namespaces to ensure that they are up to date
+and there are no temporary definitions hanging around.
+
+== "Reloaded" Workflow
+
+Typing kbd:[C-c M-n r] or kbd:[C-c M-n M-r] will invoke
+`cider-ns-refresh` and reload all modified Clojure files on the
+classpath.
+
+Adding a prefix argument, kbd:[C-u C-c M-n r], will reload all
+the namespaces on the classpath unconditionally, regardless of their
+modification status.
+
+Adding a double prefix argument, kbd:[C-u C-u M-n r], will first
+clear the state of the namespace tracker before reloading. This is
+useful for recovering from some classes of error that normal reloads
+would otherwise not recover from. A good example is circular
+dependencies. The trade-off is that stale code from any deleted files
+may not be completely unloaded.
+
+`cider-ns-refresh` wraps
+https://github.com/clojure/tools.namespace[clojure.tools.namespace], and as
+such the same
+https://github.com/clojure/tools.namespace#reloading-code-motivation[benefits]
+and
+https://github.com/clojure/tools.namespace#reloading-code-preparing-your-application[caveats]
+regarding writing reloadable code also apply.
+
+The above three operations are analogous to
+http://clojure.github.io/tools.namespace/#clojure.tools.namespace.repl/refresh[`clojure.tools.namespace.repl/refresh`],
+http://clojure.github.io/tools.namespace/#clojure.tools.namespace.repl/refresh-all[`clojure.tools.namespace.repl/refresh-all`]
+and
+http://clojure.github.io/tools.namespace/#clojure.tools.namespace.repl/clear[`clojure.tools.namespace.repl/clear`]
+(followed by a normal refresh), respectively.
+
+=== Configuration
+
+You can define Clojure functions to be called before reloading, and after a
+successful reload, when using `cider-ns-refresh`:
+
+[source,lisp]
+----
+(setq cider-ns-refresh-before-fn "user/stop-system!"
+ cider-ns-refresh-after-fn "user/start-system!")
+----
+
+These must be set to the namespace-qualified names of vars bound to
+functions of no arguments. The functions must be synchronous
+(blocking), and are expected to be side-effecting - they will always
+be executed serially, without retries.
+
+By default, messages regarding the status of the in-progress reload
+will be displayed in the echo area after you call
+`cider-ns-refresh`. The same information will also be recorded in the
+`+*cider-ns-refresh-log*+` buffer, along with anything printed to
+`+*out*+` or `+*err*+` by `cider-ns-refresh-before-fn` and
+`cider-ns-refresh-start-fn`.
+
+You can make the `+*cider-ns-refresh-log*+` buffer display automatically
+after you call `cider-ns-refresh` by setting the
+`cider-ns-refresh-show-log-buffer` variable to a non-nil value. This
+will also prevent any related messages from also being displayed in
+the echo area.
+
+[source,lisp]
+----
+(setq cider-ns-refresh-show-log-buffer t)
+----
+
+By default, CIDER will prompt for whether to save all modified `clojure-mode`
+buffers visiting files on the classpath. You can customize this behavior with
+`cider-ns-save-files-on-refresh` and `cider-ns-save-files-on-refresh-modes`.
+
+=== Using clj-reload
+
+You can also use https://github.com/tonsky/clj-reload[clj-reload] instead.
+It provides support for
+https://github.com/tonsky/clj-reload/blob/469da68/README.md#usage-keeping-vars-between-reloads[keeping
vars between reloads]
+among some
+https://github.com/tonsky/clj-reload/blob/469da68/README.md#comparison-toolsnamespace[other
differences]
+from `tools.namespace`.
+
+[source,lisp]
+----
+(setq cider-ns-code-reload-tool 'clj-reload)
+----
+
+With `clj-reload` you should set the source dirs as described in
+https://github.com/tonsky/clj-reload/blob/469da68/README.md##usage[the usage
docs]
+. If you don't set them manually, it will default to the current project's
resource dirs in the same
+way `tools.namespace` does.
+
+== Basic Code Reloading
+
+Sometimes, `cider-ns-refresh` may not work for you. If you're looking
+for a bit more forceful reloading the `cider-ns-reload`
+and `cider-ns-reload-all` commands can be used instead. These commands
+invoke Clojure's `+(require ... :reload)+` and `+(require
+... :reload-all)+` commands at the REPL.
+
+TIP: Theses commands don't depend on `cider-nrepl`, so they are always
available.
+
+== Keybindings
+
+|===
+| Command | Keyboard shortcut | Description
+
+| `cider-ns-refresh`
+| kbd:[C-c M-n r] +
+kbd:[C-c M-n M-r]
+| Reload all modified Clojure files on the classpath. Adding a prefix
argument, kbd:[C-u C-c M-n r], will reload all the namespaces on the classpath
unconditionally, regardless of their modification status. Adding a double
prefix argument, kbd:[C-u C-u M-n r], will first clear the state of the
namespace tracker before reloading.
diff --git a/doc/modules/ROOT/pages/usage/misc_features.adoc
b/doc/modules/ROOT/pages/usage/misc_features.adoc
index cfa2f93ea4..4147587929 100644
--- a/doc/modules/ROOT/pages/usage/misc_features.adoc
+++ b/doc/modules/ROOT/pages/usage/misc_features.adoc
@@ -50,103 +50,6 @@ Don't forget you also have a couple of third-party
alternative:
- The much more sophisticated AST-powered "find usages" provided by
`clj-refactor.el`
- https://github.com/bbatsov/projectile[Projectile's] "grep in project"
(`projectile-grep`, typically bound to kbd:[C-c p g])
-== Reloading Code
-
-While Clojure's and CIDER's interactive programming style means you'll
-restart your application far less often than with other languages and
-development environments, sometimes you'll want to clean everything up
-and reload one or more namespaces to ensure that they are up to date
-and there are no temporary definitions hanging around.
-
-Typing kbd:[C-c M-n r] or kbd:[C-c M-n M-r] will invoke
-`cider-ns-refresh` and reload all modified Clojure files on the
-classpath.
-
-Adding a prefix argument, kbd:[C-u C-c M-n r], will reload all
-the namespaces on the classpath unconditionally, regardless of their
-modification status.
-
-Adding a double prefix argument, kbd:[C-u C-u M-n r], will first
-clear the state of the namespace tracker before reloading. This is
-useful for recovering from some classes of error that normal reloads
-would otherwise not recover from. A good example is circular
-dependencies. The trade-off is that stale code from any deleted files
-may not be completely unloaded.
-
-`cider-ns-refresh` wraps
-https://github.com/clojure/tools.namespace[clojure.tools.namespace], and as
-such the same
-https://github.com/clojure/tools.namespace#reloading-code-motivation[benefits]
-and
-https://github.com/clojure/tools.namespace#reloading-code-preparing-your-application[caveats]
-regarding writing reloadable code also apply.
-
-The above three operations are analogous to
-http://clojure.github.io/tools.namespace/#clojure.tools.namespace.repl/refresh[`clojure.tools.namespace.repl/refresh`],
-http://clojure.github.io/tools.namespace/#clojure.tools.namespace.repl/refresh-all[`clojure.tools.namespace.repl/refresh-all`]
-and
-http://clojure.github.io/tools.namespace/#clojure.tools.namespace.repl/clear[`clojure.tools.namespace.repl/clear`]
-(followed by a normal refresh), respectively.
-
-You can define Clojure functions to be called before reloading, and after a
-successful reload, when using `cider-ns-refresh`:
-
-[source,lisp]
-----
-(setq cider-ns-refresh-before-fn "user/stop-system!"
- cider-ns-refresh-after-fn "user/start-system!")
-----
-
-These must be set to the namespace-qualified names of vars bound to
-functions of no arguments. The functions must be synchronous
-(blocking), and are expected to be side-effecting - they will always
-be executed serially, without retries.
-
-By default, messages regarding the status of the in-progress reload
-will be displayed in the echo area after you call
-`cider-ns-refresh`. The same information will also be recorded in the
-`+*cider-ns-refresh-log*+` buffer, along with anything printed to
-`+*out*+` or `+*err*+` by `cider-ns-refresh-before-fn` and
-`cider-ns-refresh-start-fn`.
-
-You can make the `+*cider-ns-refresh-log*+` buffer display automatically
-after you call `cider-ns-refresh` by setting the
-`cider-ns-refresh-show-log-buffer` variable to a non-nil value. This
-will also prevent any related messages from also being displayed in
-the echo area.
-
-[source,lisp]
-----
-(setq cider-ns-refresh-show-log-buffer t)
-----
-
-By default, CIDER will prompt for whether to save all modified `clojure-mode`
-buffers visiting files on the classpath. You can customize this behavior with
-`cider-ns-save-files-on-refresh` and `cider-ns-save-files-on-refresh-modes`.
-
-Sometimes, `cider-ns-refresh` may not work for you. If you're looking
-for a bit more forceful reloading the `cider-ns-reload`
-and `cider-ns-reload-all` commands can be used instead. These commands
-invoke Clojure's `+(require ... :reload)+` and `+(require
-... :reload-all)+` commands at the REPL.
-
-You can also use https://github.com/tonsky/clj-reload[clj-reload] instead.
-It provides support for
-https://github.com/tonsky/clj-reload/blob/469da68/README.md#usage-keeping-vars-between-reloads[keeping
vars between reloads]
-among some
-https://github.com/tonsky/clj-reload/blob/469da68/README.md#comparison-toolsnamespace[other
differences]
-from `tools.namespace`.
-
-[source,lisp]
-----
-(setq cider-ns-code-reload-tool 'clj-reload)
-----
-
-With `clj-reload` you should set the source dirs as described in
-https://github.com/tonsky/clj-reload/blob/469da68/README.md##usage[the usage
docs]
-. If you don't set them manually, it will default to the current project's
resource dirs in the same
-way `tools.namespace` does.
-
== CIDER Selector
The `cider-selector` (kbd:[C-c M-s]) command allows you to quickly navigate to
