Update nREPL server doc with supported and unsupported editors (#940)

Hi,

I have updated the nREPL server documentation in the `cli` section to
provide new instructions on how users can start the server for their
editor.

Additionally, I've a reference to it in the `REPL` page, so users whoa
re likely to be looking for the nREPL server, can locate it more easily.
I consider promoting the nREPL section to a new page next to `REPL`, but
decided to be discreet for now.

Any feedback would be greatly appreciated.

Thanks

---------

Co-authored-by: ikappaki <[email protected]>

Author: ikappaki

docs/cli.rst

@@ -37,28 +37,82 @@ The builtin REPL supports basic code completion suggestions, syntax highlighting
 Start an nREPL Session
 ----------------------
 
+An nREPL server provides an interactive REPL environment for remote code execution and development from an editor.
+
 Basilisp's CLI incorporates an nREPL server adapted from `nbb <https://github.com/babashka/nbb>`_.
 
-To start the server from the command line use the following command
+Start from an editor with a Clojure extension supporting Basilisp
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+   The extension's ``Jack-in`` command is used to start an nREPL session and connect your editor to it.
+
+With Emacs `CIDER v1.14 <https://docs.cider.mx/cider/platforms/basilisp.html>`_ and Visual Studio Code `Calva v2.0.453 <https://calva.io/basilisp/>`_ or later, you can ``Jack-in`` to a Basilisp project directly.
+The extensions also recognize Basilisp ``.lpy`` files as Clojure files.
+
+To ``Jack-in`` to a Basilisp project
+
+1. Ensure that a ``basilisp.edn`` file is present at the root of your project, even if it is empty.
+2. Run the ``Jack-in`` command in your editor and select ``Basilisp`` if prompted.
+   The Editor should then start the server and connect to it.
+
+Start from an editor with a Clojure extension not yet supporting Basilisp
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. note::
+
+   The extension's ``connect`` command is used to connect your editor to a running nREPL server.
+   It requires the port number where the server is running at.
+
+.. note::
+
+   Basilisp code files use the ``.lpy`` filename suffix.
+   You might need to adjust your editor's extension settings to recognize this suffix as a Clojure file.
+   Alternatively, you can evaluate code inside ``.clj`` files, though importing these files from other Basilisp files might not be possible due to the different file extension.
+
+If your editor extension does not yet support Basilisp, or if you prefer more control over the nREPL server, you can start the server from the command line and connect to using your extension's ``connect`` command.
+
+The nREPL server when started will provide the host and port number it is listening on.
+
+To view available command line options, use
+
+.. code-block:: bash
+
+   basilisp nrepl-server -h
+
+
+To start the server on a random port, use
 
 .. code-block:: bash
 
    basilisp nrepl-server
    # => nREPL server started on port 50407 on host 127.0.0.1 - nrepl://127.0.0.1:50407
 
-You can then establish a connection from your IDE to the server address.
 
-- from `Emacs`, using `CIDER <https://github.com/clojure-emacs/cider>`_
+To start the server on a specific port, use
+
+.. code-block:: bash
+
+   basilisp nrepl-server --port 8889
+   #=> nREPL server started on port 8889 on host 127.0.0.1 - nrepl://127.0.0.1:8889
 
-  .. code-block::
+Some extensions can connect to a running server automatically by looking for a ``.nrepl-port`` file at the root of the project. This file contains the port the server is listening on.
 
-     M-x cider-connect-clj
+The ``nrepl-server`` command will generate this file in the current working directory where the server is started.
+If your extension's ``connect`` command looks for this file, run the server command from the root of the project, so that is generated in there
 
-- from `Visual Studio Code`, using `Calva <https://calva.io/>`_
+.. code-block:: bash
 
-  .. code-block::
+   cd <project-root-directory>
+   basilisp nrepl-server
+   #=> nREPL server started on port 632128 on host 127.0.0.1 - nrepl://127.0.0.1:63128
+
+Alternatively, specify the full path where this file should be generated using the ``--port-filepath`` CLI option
+
+.. code-block:: bash
 
-     REPL -> Connect to a running REPL in your project -> Generic
+   basilisp nrepl-server --port-filepath <project-root-directory>/.nrepl-port
+   #=> nREPL server started on port 62079 on host 127.0.0.1 - nrepl://127.0.0.1:62079
 
 .. _run_basilisp_code:
 
@@ -145,4 +199,4 @@ If you would like to remove the bootstrapped Basilisp from your installation, yo
 
 .. code-block:: bash
 
-   basilisp bootstrap --uninstall
+   basilisp bootstrap --uninstall

docs/repl.rst

@@ -22,6 +22,10 @@ The default REPL namespace is ``basilisp.user``, but users can modify that at st
 
    REPL is an acronym meaning ``Read-Eval-Print-Loop`` which is refreshingly self-descriptive.
 
+.. seealso::
+
+   :ref:`start_an_nREPL_session`
+
 .. _repl_utilities:
 
 REPL Utilities