Merge pull request #397 from alphaville/docs/docusaurus-v3-upgrade

Upgrade to Docusaurus v3

Author: alphaville

.gitignore

@@ -43,6 +43,7 @@ open-clib/Cargo.lock
 /website/node_modules/
 /website/yarn.lock
 /website/build/
+/website/.docusaurus/
 !/website/pages/
 !/website/static/
 !/website/*.js
@@ -73,4 +74,4 @@ open-clib/Cargo.lock
 *private*
 .DS_Store
 /img/
-private/
+private/

docs/docker.md

@@ -2,115 +2,147 @@
 id: docker
 title: Docker
 sidebar_label: Docker
-description: Docker image of a Jupyter Python Notebook to run OpEn
+description: Docker image of a JupyterLab environment to run OpEn
 ---
 
 <img src="/optimization-engine/img/docker.gif" alt="OpEn in Docker container" width="200"/>
 
 ## What is Docker?
 
-[Docker](https://www.docker.com/) is a tool that facilitates the execution and deployment of applications (often web applications) using containers. Containers package the applications along with the entirety of its context such as libraries and configuration files. You may think of containers as independent, isolated and self-sufficient processes. A container is then guaranteed to run on any other Linux-based machine regardless of the exact operating system, local configurations. 
+[Docker](https://www.docker.com/) is a tool for packaging applications and their dependencies into containers. A container can run on different machines without requiring you to recreate the same environment manually.
 
-Docker has nowadays become extremely popular. Developers package their software in bundles known as *Docker images* which can be stored in Docker Hub: an online repository. Then the users can obtain such images and run them locally.
-
-Docker is open-source and free and can be easily installed on any Linux, Mac OSX or Windows machine. 
-
-
-## What is a Jupyter Notebook?
-According to [jupyter.org](https://jupyter.org/), "JupyterLab is a web-based interactive development environment for Jupyter notebooks, code, and data."
+## What is JupyterLab?
 
+According to [jupyter.org](https://jupyter.org/), JupyterLab is a web-based development environment for notebooks, code, and data.
 
 ## Requirements
 
-You need to have Docker installed ([instructions](https://docs.docker.com/get-docker/)).
+You need to have Docker installed. See the [official installation instructions](https://docs.docker.com/get-docker/).
 
-## Pull and Use Docker Image
+## Pull and Run the Docker Image
 
-Hmm.. that [OpEn](https://alphaville.github.io/optimization-engine/) framework looks really cool. I wonder whether it is possible to try it out very quickly without installing much...
+You can download the current Docker image using:
 
-TaDaaa...
+```console
+docker pull alphaville/open:0.6.0
+```
 
-You can now download this docker image using
+and then run it with:
 
 ```console
-docker pull alphaville/open
+docker run --name open-jupyter -p 127.0.0.1:8888:8888 -it alphaville/open:0.6.0
 ```
 
-and then run it with
+This starts JupyterLab and makes it available at:
 
-```console
-docker run -p 8888:8888 -it --name=open-notebook alphaville/open
+- [http://127.0.0.1:8888/lab](http://127.0.0.1:8888/lab)
+
+The image currently includes:
+
+- Python 3.12
+- `opengen==0.10.0`
+- JupyterLab
+- Rust installed through `rustup`
+- Example notebooks under `/open/notebooks`
+
+By default, JupyterLab starts with token authentication enabled. To view the token:
+
+```bash
+docker logs open-jupyter
 ```
-It will start a Jupyter Notebook at [localhost:8888](http://localhost:8888) without a password.
 
-It is always a good idea to give your docker container a name using `--name`. For example
+It is always a good idea to give your container a name using `--name`.
 
 <div class="alert alert-info">
-<b>Info:</b> Use <code>docker run alphaville/open</code> only the first time you run the container. Use <code>docker start {container_name}</code> all subsequent times. Always give a name to your containers.</div>
+<b>Info:</b> Use <code>docker run</code> only the first time you create the container. Use <code>docker start -ai open-jupyter</code> to start it again later.</div>
 
 <div class="alert alert-success">
-<b>Tip:</b> To stop a running container do <code>docker stop {container_name}</code>.</div>
+<b>Tip:</b> To stop a running container, do <code>docker stop open-jupyter</code>.</div>
 
+## Configure the Docker Image
 
-## Configure Docker Image
+### Configure password-based access
 
-### Configure password
+To run JupyterLab with a password instead of the default token, provide a hashed password through `JUPYTER_NOTEBOOK_PASSWORD`:
 
-To set up a password for your Python Notebook:
+```bash
+docker run \
+  --name open-jupyter \
+  -e JUPYTER_NOTEBOOK_PASSWORD='your hashed password' \
+  -p 127.0.0.1:8888:8888 \
+  -it alphaville/open:0.6.0
+```
 
-- <a href="https://jupyter-notebook.readthedocs.io/en/stable/public_server.html#hashed-pw" target="_blank">Hash your password</a>
-- Run your docker image with:
+For password hashing instructions, see the [Jupyter Server documentation](https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html).
 
-```
-docker run  \
-  -e JUPYTER_NOTEBOOK_PASSWORD={your hashed password}  \
-  -p 8888:8888  \
-  --name=open-notebook  \
-  alphaville/open
-```
+<details>
+  <summary>How to set up a password</summary>
 
-For example, let's say you want to set the password **open**. Then do
+  You can read more about how to set up a password for your 
+  Python notebook [here](https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html).
+  TL;DR: run the following command:
 
-```console
-docker run   \
-  -e JUPYTER_NOTEBOOK_PASSWORD=sha1:898ca689bf37:2ee883bfd6ffe82a749a86e37964700bd06a2ff9  \
-  -p 8888:8888  \
-  --name=open-notebook  \
-  alphaville/open
-```
+  ```bash
+  docker run --rm -it --entrypoint /venv/bin/python \
+    alphaville/open:0.6.0 \
+    -c "from jupyter_server.auth import passwd; print(passwd())"
+  ```
+
+  You will be asked to provide your password twice. Then a string 
+  will be printed; this is your hashed password.
+</details>
 
 ### Configure port
 
-You can access the Jupyter Notebook at a different port by configuring the port forwarding of Docker. For example, to run on port 80 run:
+You can access JupyterLab on a different host port by changing Docker's port forwarding. For example, to use port `80` on your machine:
 
-```console
-docker run -p 80:8888 alphaville/open
+```bash
+docker run -p 80:8888 alphaville/open:0.6.0
 ```
 
-Then, Jupyter Notebook will be accessible at http://localhost.
-The argument `-p 80:8888` means that the internal port `8888` is mapped to the host's port `80`.
+Then JupyterLab will be available at `http://localhost/lab`.
 
+### Work with notebooks
 
-### Load additional python packages
+The bundled example notebook is available inside the container at:
 
-You can load any packages you like in your Python Notebook using `pip3` and prepend a `!` to your command. For example, if you want to load `matplotlib`, do 
+```text
+/open/notebooks/example.ipynb
+```
+
+To persist your own notebooks across container restarts, mount a Docker volume onto `/open`:
+
+```bash
+docker volume create OpEnVolume
+docker run --name open-jupyter \
+  --mount source=OpEnVolume,destination=/open \
+  -p 127.0.0.1:8888:8888 \
+  -it alphaville/open:0.6.0
+```
+
+### Load additional Python packages
+
+You can install additional packages from inside JupyterLab. For example:
 
 ```python
-!pip3 install matplotlib
+!pip install matplotlib
 ```
 
-If you install a Python package in a certain docker container, it will be there the next time you access it.
+Packages installed into a persistent container or volume-backed environment will still be there the next time you access it.
 
-### Open terminal into docker container
+### Open a terminal in the container
 
-Suppose you have a running docker container with name `open-notebook` (you may specify a name for your docker container when you start it using `--name`). To open a terminal into it you can run
+Suppose you have a running Docker container with name `open-jupyter`. To open a shell in it:
 
-```console
-docker exec -it open-notebook /bin/bash
+```bash
+docker exec -it open-jupyter /bin/bash
 ```
 
+The Python virtual environment is available at `/venv`.
+
 ### Download your optimizer
-To download your optimizer from Jupyter you first need to create an archive ot it. You can do that using `tar` as follows
+
+To download a generated optimizer from JupyterLab, first create an archive:
 
 ```python
 !tar -cf rosenbrock.tar.gz optimizers/rosenbrock

docs/example-nmpc.md

@@ -2,7 +2,7 @@
 id: example-nmpc
 title: Control of population dynamics
 sidebar_label: Population dynamics
-description: Nonlinear model predictive control with OpEn: population dynamics
+description: "Nonlinear model predictive control with OpEn: population dynamics"
 ---
 <script type="text/x-mathjax-config">MathJax.Hub.Config({tex2jax: {inlineMath: [['$','$'], ['\\(','\\)']]}});</script>
 <script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>

docs/example_bnp_py.md

@@ -214,7 +214,7 @@ builder.build()
 ```
 
 This will generate a solver in Rust as well as a [TCP server](./python-tcp-ip) that will 
-listen for requests at `localhost:8333` (this [can be configured](python-advanced#tcp-ip-interface)).
+listen for requests at `localhost:8333` (this [can be configured](python-advanced#tcpip-interface)).