fix: update poetry & improve instructions (#19)

* fix: update poetry

* fix: avoid warning in newer poetry version

```
Installing the current project: ds-user-guide (0.1.0)
Warning: The current project could not be installed: No file/folder found for package ds-user-guide
If you do not want to install the current project use --no-root.
If you want to use Poetry only for dependency management but not for packaging, you can disable package mode by setting package-mode = false in your pyproject.toml file.
In a future version of Poetry this warning will become an error!
```

* docs: improve instructions

* docs(README): mention and link to Python versions

* docs(README): clearer steps

Dockerfile

@@ -5,7 +5,7 @@ LABEL maintainer="TACC-ACI-WMA <[email protected]>"
 ARG DEBIAN_FRONTEND=noninteractive
 
 # https://python-poetry.org/docs/configuration/#using-environment-variables
-ENV POETRY_VERSION=1.4.2 \
+ENV POETRY_VERSION=1.8.2 \
     POETRY_HOME="/opt/poetry" \
     POETRY_VIRTUALENVS_IN_PROJECT=true \
     POETRY_NO_INTERACTION=1 \

README.md

@@ -16,31 +16,39 @@ DesignSafe ReadTheDocs Documentation with [MkDocs](https://mkdocs.readthedocs.io
 
 ## Local Development
 
-### Using Local Environment
-
-> More control. More caveats.
-
-If you have not already, create a virtual environment that uses Python 3.11.
-
-```shell
-cd DS-User-Guide
-pip install poetry
-poetry install
-cd user-guide
-mkdocs serve
-```
-
-### Using Pre-Configured Environment
-
-> Less control. Less caveats.
-
-If you have not already, follow [TACC/TACC-Docs prequisites for running the docs "via Docker"](https://github.com/TACC/TACC-Docs#via-docker).
-
-```shell
-cd DS-User-Guide
-make build
-make start
-```
+### A. Via Python
+
+0. Have Python installed.\
+    <sup>Known supported versions are [from 3.10 to 3.12](https://github.com/DesignSafe-CI/DS-User-Guide/blob/6c22d2f/pyproject.toml).</sup>
+1. Navigate into your clone of this repo.
+2. Install dependencies:\
+    <sup>You should only need to do this once.</sup>
+    ```shell
+    pip install poetry
+    poetry install
+    ```
+4. Serve the docs:
+    ```shell
+    poetry shell
+    cd user-guide
+    mkdocs serve
+    ```
+    <sup>After the `poetry shell` command, you should be in a Poetry-managed environment. Your prompt might be prefixed with the name of the environment.</sup>
+5. Open the website _at the URL echoed by the program_, e.g.
+    http://127.0.0.1:8000/user-guide/
+
+### B. Via Docker
+
+0. Have Docker installed.\
+    <sup>We recommend doing so via [Docker-Desktop](https://www.docker.com/products/docker-desktop).</sup>
+1. Navigate into your clone of this repository.
+2. Start the Docker container to serve the docs.
+    ```shell
+    make build
+    make start
+    ```
+3. Open the website at the URL provided e.g.
+    http://0.0.0.1:8000/user-guide/
 
 ## Releases
 

pyproject.toml

@@ -2,6 +2,7 @@
 name = "ds-user-guide"
 version = "0.1.0"
 description = ""
+package-mode = false
 authors = ["rstijerina <[email protected]>"]
 
 [tool.poetry.dependencies]