branch: elpa/cider
commit 0916372cdd285b058c25d13bf7759941363e767b
Author: ikappaki <34983288+ikapp...@users.noreply.github.com>
Commit: GitHub <nore...@github.com>
[Docs] Improve the basilisp doc structure (#3703)
Co-authored-by: ikappaki <ikapp...@users.noreply.github.com>
---
doc/modules/ROOT/nav.adoc | 1 +
doc/modules/ROOT/pages/platforms/basilisp.adoc | 56 +++++++++++++++-----------
2 files changed, 34 insertions(+), 23 deletions(-)
diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc
index 06035fd885..61e5ac19c9 100644
--- a/doc/modules/ROOT/nav.adoc
+++ b/doc/modules/ROOT/nav.adoc
@@ -14,6 +14,7 @@
** xref:platforms/overview.adoc[Overview]
** xref:platforms/babashka.adoc[Babashka]
** xref:platforms/nbb.adoc[Nbb]
+** xref:platforms/basilisp.adoc[Basilisp]
** xref:platforms/other_platforms.adoc[Other Platforms]
* Using CIDER
** xref:usage/interactive_programming.adoc[Interactive Programming]
diff --git a/doc/modules/ROOT/pages/platforms/basilisp.adoc
b/doc/modules/ROOT/pages/platforms/basilisp.adoc
index 4bef08daa4..1859f5d803 100644
--- a/doc/modules/ROOT/pages/platforms/basilisp.adoc
+++ b/doc/modules/ROOT/pages/platforms/basilisp.adoc
@@ -5,7 +5,7 @@ since CIDER 1.14
== Overview
-Basilisp aims to enable writing Clojure programs on Python with full Python
interoperability. It is highly compatible with Clojure.
+Basilisp aims to enable writing Clojure programs on Python with full
interoperability. It is highly compatible with Clojure.
To install Basilisp, run:
@@ -15,16 +15,18 @@ To install Basilisp, run:
There are several ways to connect to Basilisp.
-* kbd:[M-x cider-jack-in] and kbd:[M-5 M-x cider-jack-in-universal]
+=== jack-in
-If you have created a `basilisp.edn` project file at your root of your project
tree, you can jack in to the project `M-x cider-jack-in`. The `basilisp.edn` is
similar to `deps.edn` for clojure-cli projects. It can be left empty just to
mark the root of your project.
+kbd:[M-x cider-jack-in] and kbd:[M-5 M-x cider-jack-in-universal]
+
+If you have created a `basilisp.edn` project file at your root of your project
tree, you can jack in to the project with `M-x cider-jack-in`. The
`basilisp.edn` is similar to `deps.edn` for clojure-cli projects. It can be
left empty just to mark the root of your project.
If you don't have or want a basilisp project file, you can use universal jack
in with a numerical argument of 5:
- kbd:[M-5 M-x cider-jack-in-universal], or
-- kbd:[M-5 C-c C-x j u], from within file in clojure-mode
+- kbd:[M-5 C-c C-x j u], from within a file in clojure-mode
-(Note: an alternative to kbd:[M-5] is kbd:[C-u 5])
+NOTE: an alternative to kbd:[M-5] is kbd:[C-u 5]
You can also bind the universal jack-in to Basilisp to a function to use as a
shortcut, for example
@@ -35,7 +37,9 @@ You can also bind the universal jack-in to Basilisp to a
function to use as a sh
(cider-jack-in-universal 5)))
----
-* kbd:[M-x cider-connect]
+=== connect
+
+kbd:[M-x cider-connect]
You can start its bundled nREPL server:
@@ -47,31 +51,37 @@ To see available options, type `basilisp nrepl-server -h`
in a shell prompt.
== Configuration
-The jack-in command can be configured via several defcustoms:
+The jack-in command can be configured with the following defcustoms
+
+=== `cider-basilisp-command`
-* `cider-basilisp-command` (default is `basilisp`).
+(default is `basilisp`)
If Basilisp is installed in a virtual environment, update this to the full
path of the `basilisp` executable within that virtual environment.
-* `cider-basilisp-parameters` (default is `nrepl-server`).
+=== `cider-basilisp-parameters`
+
+(default is `nrepl-server`)
+
+=== Customization
There at few ways to setup (custom) variables in Emacs
--
https://www.gnu.org/software/emacs/manual/html_node/emacs/Easy-Customization.html[Examining
and Setting Variables]
+==== 1.
https://www.gnu.org/software/emacs/manual/html_node/emacs/Easy-Customization.html[Examining
and Setting Variables]
-kbd:[C-h v cider-basilisp-command], and
-kbd:[C-h v cider-basilisp-parameters]
+- kbd:[C-h v cider-basilisp-command], and
+- kbd:[C-h v cider-basilisp-parameters]
--
https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html[Per-Diretory
Local Variables]
+==== 2.
https://www.gnu.org/software/emacs/manual/html_node/emacs/Directory-Variables.html[Per-Diretory
Local Variables]
Uses `.dir-locals.el` to setup per mode variables. This file is typically
stored at the root of the project.
For example, to set the path to the basilisp executable within a virtual
environment
-kbd:[M-x add-dir-local-variable]
-Mode or subdirectory: `clojure-mode`
-Add directory-local variable: `cider-basilisp-command`
-Add cider-basilisp-command with value: `"c:/dev/venvs/312/Scripts/basilisp"`
+- kbd:[M-x add-dir-local-variable]
+- Mode or subdirectory: `clojure-mode`
+- Add directory-local variable: `cider-basilisp-command`
+- Add cider-basilisp-command with value: `"c:/dev/venvs/312/Scripts/basilisp"`
This should result to updating or creating a `.dir-local.el` file like below
@@ -83,15 +93,15 @@ This should result to updating or creating a
`.dir-local.el` file like below
((clojure-mode . ((cider-basilisp-command .
"c:/dev/venvs/312/Scripts/basilisp"))))
----
--
https://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html[Specifying
File Variables]
+==== 3.
https://www.gnu.org/software/emacs/manual/html_node/emacs/Specifying-File-Variables.html[Specifying
File Variables]
-It is best to put this in the top of your project's `basilisp.edn` file, and
always jack-in from there
+It is best to put this in the top of your project's `basilisp.edn` file, and
always jack-in from there.
-For example, setting `cider-basilisp-command` to start basilisp from within a
virtual environment
+For example, setting `cider-basilisp-command` to start basilisp from within a
virtual environment:
-kbd:[M-x add-dir-local-variable]
-Add file-local variable: `cider-basilisp-command`
-Add cider-basilisp-command with value: `"c:/dev/venvs/312/Scripts/basilisp"`
+- kbd:[M-x add-dir-local-variable]
+- Add file-local variable: `cider-basilisp-command`
+- Add cider-basilisp-command with value: `"c:/dev/venvs/312/Scripts/basilisp"`
This will result in the following in `basilisp.edn`
