From 1bc3d23f39265b195bc2236c165bb1f2834b618b Mon Sep 17 00:00:00 2001 From: ikappaki Date: Mon, 2 Dec 2024 07:42:52 +0000 Subject: [PATCH] doc update --- .github/workflows/test.yml | 1 + README.md | 31 +++++++++++++++---------------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b002ac9..0dbd89a 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,6 +1,7 @@ name: Basilisp Jupyter Kernel package on: + pause: pull_request: types: [ opened, synchronize, reopened ] push: diff --git a/README.md b/README.md index 5459d01..2b4173c 100644 --- a/README.md +++ b/README.md @@ -74,15 +74,15 @@ For additional configuration options, such as specifying a port with `:port` or ## Getting started with Basilisp Notebooks -### Batteries Included Project +### Batteries Included Project: `basilex-notebook` -The Basilisp Example Notebook repository, [basilex-notebook](https://github.com/ikappaki/basilex-notebook), is an excellent resource for exploring Basilisp notebooks. This project includes Jupyter, the Basilisp kernel, a skeleton Basilisp library, and a development notebook to help you get started. +The [Basilisp Example Notebook](https://github.com/ikappaki/basilex-notebook) repository, is an good resource for exploring Basilisp notebooks. It includes Jupyter, the Basilisp kernel, a skeleton Basilisp library, and a development notebook to help you get started. #### Setup -First, ensure you have [Poetry](https://python-poetry.org/docs/) installed on your system for dependency management. +1. Install [Poetry](https://python-poetry.org/docs/) for dependency management. -Then, clone the repository, install dependencies, activate the environment and run the Jupyter Notebook server +2. Clone the repository, install dependencies, activate the environment and start Jupyter: ```shell $ git clone https://github.com/ikappaki/basilex-notebook.git @@ -92,17 +92,17 @@ $ poetry shell () $ jupyter notebook ``` -From the Jupyter Notebook interface, open the `dev.ipynb` notebook to start development. For additional details, refer to the [basilex-notebook documentation](https://github.com/ikappaki/basilex-notebook). +3. Open the `dev.ipynb` notebook from the Jupyter interface. Refer to the [basilex-notebook documentation](https://github.com/ikappaki/basilex-notebook) for more details. -### Basilisp Library Project +### Basilisp Example Library Project: `basilex-basilib` -You can develop Basilisp Clojure code in an external library and integrate it into your Notebooks. Use the [basilex-basilib](https://github.com/ikappaki/basilex-basilib) Basilisp Example Library repository as an example. +Use the [Basilisp Example Library](https://github.com/ikappaki/basilex-basilib) repository to develop external Basilisp libraries for integration with your notebooks. -The following instructions assume you are running in a virtual environment where the Basilisp Notebooks will be opened from (e.g. `basiliex-notebook` above). This is indicated by the environment name prefix in your command prompt, such as `` in the examples below. +The following instructions assume you are running in a virtual environment where the Basilisp Notebooks will be opened from (e.g. such as in the `basiliex-notebook` clone above). This is indicated by the environment name prefix in your command prompt, such as `` in the examples below. #### Setup -Clone the repository and install the `basilib` library as an editable package in your virtual environment: +Clone the repository and install the `basilib` library as an editable package in in the same virtual environment as your Basilisp notebooks: ```shell () $ git clone https://github.com/ikappaki/basilex-basilib.git @@ -113,7 +113,7 @@ Clone the repository and install the `basilib` library as an editable package in #### Usage -Once installed, you can load and interact with the library in your notebook: +Load and interact with the library in your notebooks: ```clojure [n]: (require '[basilib.core :as bc]) @@ -126,18 +126,17 @@ Once installed, you can load and interact with the library in your notebook: > [!NOTE] > Refer to [Connecting Your Editor to the nREPL Server](https://github.com/ikappaki/basilisp-kernel/wiki/Connecting-Your-Editor-to-the-nREPL-Server) for detailed instructions, covering various use cases. -For interactive development, you can use your preferred Clojure-Enabled Editor in conjuction with a running nREPL server in your Basilisp notebook. +For interactive coding, you can connect your preferred Clojure-Enabled Editor to a running nREPL server in your Basilisp Notebook. ##### Start the nREPL server -The following instructions are assumed to be executed in Notebook cells running the Basilisp Kernel, as indicated by the [n]: prefix. +In a notebook cell: -First load the nREPL server namespace +1. Load the nREPL server namespace: ```clojure [n]: (require '[basilisp-kernel.nrepl-server :as nrepl-server]) ``` -Then, start the nREPL server on a fixed port - +2. Start the nREPL server on a fixed port: ```Clojure [n]: (def server (server-start {:port 9998})) nREPL server started on port 9998 on host 127.0.0.1 - nrepl://127.0.0.1:9998 @@ -146,7 +145,7 @@ nREPL server started on port 9998 on host 127.0.0.1 - nrepl://127.0.0.1:9998 ##### Connect to the nREPL Server -In your code Editor, open the `basilisp.edn` file located in your project root directory (e.g. `basilex-notebook`, `basilex-basilib` or your own Basilisp Project) to enable Clojure-specific features in your editor. Then, use your editor's commands to connect to the nREPL server. +In your code Editor, open the `basilisp.edn` file located in your project root directory (e.g. in `basilex-notebook`, `basilex-basilib` or your own Basilisp Project) to enable Clojure-specific features in your editor. Then, use your editor's commands to connect to the nREPL server. Both [Emacs/CIDER](https://docs.cider.mx/cider/platforms/basilisp.html) and [VSCode/Calva](https://calva.io/basilisp/) offer explicit support for Basilisp.