Merge pull request 'docs: focus on local install, ".env" before "make setup"' (#31) from readme-revamp into master

Reviewed-on: varia/octomode#31

README.md

@@ -6,37 +6,29 @@ Octomode is a collective editing space for PDF making, using Etherpad, Paged.js
 
 Inspired by the multi-centered, tentacular cognition capabilities of the octopus, we imagined a space in which the artificial boundaries of writing and design can be crossed; where writing, editing and designing can be done in one environment simultaneously, allowing the format to influence the matter and vice-versa.
 
-More expanded documentation can be found here: <https://cc.vvvvvvaria.org/wiki/Octomode>
+More expanded documentation can be found [here](https://cc.vvvvvvaria.org/wiki/Octomode).
 
-An installation guide can be found below.
+## Local install
 
-## Install octomode
+> **WARNING**: It's recommended to use Firefox when working with Octomode
+> locally. Chrome or Chromium do not load external etherpads in iframes.
 
-You can clone this repository to run octomode on your own computer or server.
-
-`git clone https://git.vvvvvvaria.org/varia/octomode.git`
-
-Install the dependencies.
-
-All the `python` dependencies are listed in `requirements.txt`
-
-To install them, you can run:
-
-`make setup`
+### Prerequisites
 
-This creates a virtual environment at `.venv/` and installs all the dependencies here.
+* Existing [Etherpad](https://etherpad.org) installation
+* [Pandoc](https://pandoc.org/) >= 2.x
+* Python >= 3.11.x
 
-Next to this, you also need to install `pandoc`.
+### Get started
 
-`sudo apt install pandoc`
-
-Now we need to configure *octomode*:
-
-`cd octomode`
+You can clone this repository to run octomode on your own computer or server.
 
-`nano .env` 
+```
+git clone https://git.vvvvvvaria.org/varia/octomode.git
+cd octomode
+```
 
-Configure your environment, save the following configuration settings as to a file called `.env`:
+Configure your environment, save the following configuration settings as to a file called `.env`.
 
 ```
 OCTOMODE_APPLICATION_ROOT=XXX
@@ -46,35 +38,34 @@ OCTOMODE_PAD_API_URL=XXX
 OCTOMODE_PAD_API_KEY=XXX
 ```
 
+- **OCTOMODE_PAD_API_KEY**: *required*, **no default**
 - **OCTOMODE_APPLICATION_ROOT**: *optional*, default: `/`
 - **OCTOMODE_PORTNUMBER**: *optional*, default: `5001`
 - **OCTOMODE_PAD_URL**: *optional*, default: `https://pad.vvvvvvaria.org/`
 - **OCTOMODE_PAD_API_URL**: *optional*, default: `https://pad.vvvvvvaria.org/api/1.2.15/`
-- **OCTOMODE_PAD_API_KEY**: *required*, **no default**
-
-(Note: You must provide a value for `OCTOMODE_PAD_API_KEY`.)
 
-`make run` (runs the Flask application)
+**Note**: you must provide a value for `OCTOMODE_PAD_API_KEY`.
 
-Open the application at port `5001`, for example: <http://localhost:5001> or <https://mydomainname.ext:5001>.
+Now we install the dependencies. All the `python` dependencies are listed in `requirements.txt`. To install them, you can run.
 
-## Install octomode with an URL prefix
-
-If you want to install octomode with an URL prefix, like <https://mydomainname.ext/octomode/>, then you can use the gunicorn WSGI.
-
-If you have ran the `make setup` command already, then `gunicorn` is already installed.
+```
+make setup
+```
 
-Configure your application root URL in your `.env` file.
+This creates a virtual environment at `.venv` and installs all the dependencies here. Next, we also need to install `pandoc`.
 
-You can simply run *octomode* now with the following command to run it with `gunicorn` (and not the built-in Flask dev server):
+```
+sudo apt install pandoc
+```
 
-`make action`
+And finally, run the application.
 
-### Dependencies
+```
+make run
+```
 
-* pandoc
-* python dependencies, see: `requirements.txt`
+Open the application at port `5001`, for example: http://localhost:5001
 
-## Use octomode locally
+## Install with URL prefix
 
-It's recommended to use Firefox when working with octomode locally. Chrome or Chromium do not load external etherpads in iframes.
+If you want to install octomode with an URL prefix, like <https://mydomainname.ext/octomode/>, then you can use the gunicorn WSGI. If you have ran the `make setup` command already, then `gunicorn` is already installed. Configure your application root URL in your `.env` file. You can simply run *octomode* now with the following command to run it with `gunicorn` (and not the built-in Flask dev server): `make action`