diff --git a/README.md b/README.md index eac4e8d1..f9dc239b 100644 --- a/README.md +++ b/README.md @@ -74,64 +74,7 @@ See the [contributing.md](CONTRIBUTING.md) for a detailed guide on how to contri ## How to Build and Run the Site Locally -Create a local python environment and install all the required dependencies using the following commands (either with conda or pip) - -### If Using Conda -1. Create the Conda Environment -```sh -conda env create -f environment.yml -``` -2. Activate the Conda Environment -```sh -conda activate DISCOVER-Cookbook -``` -3. Finally, to build the Jupyter Book -``` sh -sphinx-build -b html DISCOVER/ DISCOVER/_build/html -``` - -### If Using pip -1. Create a Virtual Environment (optional) -```sh -python -m venv .venv -``` -2. Activate the virtual Environment (optional) -- on Windows: -```sh -.venv\Scripts\activate -``` -- on macOS/Linux: -```sh -source .venv/bin/activate -``` -3. Install the required dependencies -```sh -pip install -r requirements.txt -``` -4. Finally, to build the Jupyter Book -``` sh -sphinx-build -b html DISCOVER/ DISCOVER/_build/html -``` -### View Locally -After building, you can view the book in one of the following ways: - -#### **Option 1: Using a Local Server** -Run the following command to start a local server: -```sh -python -m http.server 8000 --directory DISCOVER/_build/html/ -``` -Then, open [`http://localhost:8000`](http://localhost:8000) in your browser. - -#### **Option 2: Opening the File Directly** -Alternatively, you can open the book directly by navigating to: -``` -DISCOVER/_build/html/index.html -``` -and opening it in your browser. - -> **Note:** Make sure you have built the book again before accessing it. - - +For full setup instructions (Conda, pip, and local preview), see **[SETUP.md](SETUP.md)**. ## Contributors ✨ diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 00000000..e6183a69 --- /dev/null +++ b/SETUP.md @@ -0,0 +1,79 @@ +# Setting Up DISCOVER-Cookbook Locally + +This guide explains how to build and run the DISCOVER-Cookbook site on your local machine. + +## Prerequisites + +You will need either **Conda** or **pip** (Python 3.x) installed. + +--- + +## Option 1: Using Conda + +1. **Create the Conda environment** + ```sh + conda env create -f environment.yml + ``` + +2. **Activate the environment** + ```sh + conda activate DISCOVER-Cookbook + ``` + +3. **Build the book** + ```sh + sphinx-build -b html DISCOVER/ DISCOVER/_build/html + ``` + +--- + +## Option 2: Using pip + +1. **Create a virtual environment** (optional but recommended) + ```sh + python -m venv .venv + ``` + +2. **Activate the virtual environment** + - On Windows: + ```sh + .venv\Scripts\activate + ``` + - On macOS/Linux: + ```sh + source .venv/bin/activate + ``` + +3. **Install dependencies** + ```sh + pip install -r requirements.txt + ``` + +4. **Build the book** + ```sh + sphinx-build -b html DISCOVER/ DISCOVER/_build/html + ``` + +--- + +## Viewing the Site Locally + +After building, you can view the book in one of two ways: + +### Option A: Using a local server (recommended) + +```sh +python -m http.server 8000 --directory DISCOVER/_build/html/ +``` + +Then open [`http://localhost:8000`](http://localhost:8000) in your browser. + +### Option B: Opening the file directly + +Navigate to: +``` +DISCOVER/_build/html/index.html +``` +and open it in your browser. + +> **Note:** Make sure you rebuild the book after making any changes before viewing.