docs: improve setup documentation (#15)

* Update README. add CONTRIBUTING & INSTALL docs * Improve a bit project title * Add pre-commit to requirements
openfoodfacts · Nov 8, 2023 · fa662c4 · fa662c4
1 parent 7b0def3
commit fa662c4
Show file tree

Hide file tree

Showing 5 changed files with 68 additions and 11 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,12 @@
+# Contributing to Open-Prices
+
+## How to install on your local machine
+
+see [INSTALL.md](https://github.com/openfoodfacts/open-prices/blob/main/INSTALL.md)
+
+## Install pre-commit
+
+This repo uses [pre-commit](https://pre-commit.com/) to enforce code styling, etc. To use it:
+```console
+pre-commit run
+```
diff --git a/INSTALL.md b/INSTALL.md
@@ -0,0 +1,34 @@
+# HOWTO install/test Open Prices API
+
+## Prerequisites
+
+- Python 3.12
+- pip
+
+## Setup
+
+```
+# clone repo
+git clone https://github.com/openfoodfacts/open-prices.git
+cd open-prices
+
+# required packages to setup a virtualenv (optional, but recommended)
+apt install python3-virtualenv virtualenv
+
+# create and switch to virtualenv
+python -m venv venv
+source venv/bin/activate
+
+# install
+pip install -r requirements.txt
+```
+
+## Run locally
+
+```
+uvicorn app.api:app --reload
+```
+or use `--host` if you want to make it available on your local network, eg.:
+```
+uvicorn app.api:app --reload --host 192.168.0.100
+```
diff --git a/README.md b/README.md
@@ -1,9 +1,16 @@
-# Open Prices
+# Open Prices API
 
-An open database of food prices.
+A REST API designed to interact with the Open Food Facts _Open Prices_ database.
 
-### Pre-Commit
-This repo uses [pre-commit](https://pre-commit.com/) to enforce code styling, etc. To use it:
-```console
-pre-commit run
-```
+## Dependencies
+
+* Python 3.12
+* [FastAPI](https://fastapi.tiangolo.com/) framework
+
+## How to install on your local machine
+
+Follow the steps in [INSTALL.md](https://github.com/openfoodfacts/open-prices/blob/main/INSTALL.md)
+
+## Contribute
+
+See [CONTRIBUTING.md](https://github.com/openfoodfacts/open-prices/blob/main/CONTRIBUTING.md)
diff --git a/app/api.py b/app/api.py
@@ -10,9 +10,12 @@
 
 logger = get_logger(level=settings.log_level.to_int())
 
-
+description = """
+Open Prices API allows you to add product prices.
+"""
 app = FastAPI(
-    title="open-prices",
+    title="Open Food Facts open-prices REST API",
+    description=description,
     contact={
         "name": "The Open Food Facts team",
         "url": "https://world.openfoodfacts.org",

diff --git a/app/templates/index.html b/app/templates/index.html
@@ -1,6 +1,7 @@
 <!DOCTYPE html>
 <html>
     <body>
-        <p>Hello world!</p>
+        <p>Hello open-prices World!</p>
+        <p>Tip: open /docs for documentation</p>
     </body>
-</html>
+</html>