diff --git a/README.md b/README.md index 8cb9b5a..5c6d49b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,18 @@ # Garbage Reminder Documentation -This documentation is under development and is not finished yet. +Documentation made with MkDocs Material for API, bots and contributions. + +## Requirements + +* Git +* Python 3.8+ (tested on 3.9 to 3.11) + +## Building the docs + +1. Clone the repo using `git clone https://git.end-play.xyz/GarbageReminder/Docs.git` +2. Go to the `Docs` directory +3. Create a virtual environment using `python -m venv .venv` +4. Activate it using `.venv/bin/activate` or `.venv\Scripts\activate.bat` +5. Install the dependencies using `pip install -r requirements.txt` +6. Build the docs using `mkdocs build` +7. Deploy as any other file-based website. The generated website is under `site` diff --git a/docs/api/configuration.md b/docs/api/configuration.md index e69de29..bb1db33 100644 --- a/docs/api/configuration.md +++ b/docs/api/configuration.md @@ -0,0 +1,38 @@ +# API configuration + +The API server stores all config keys in JSON format in the file `config.json` located under the project's root. +On this page you can find all config sections and keys that can be set. + +## database + +Configuration section where all database-related keys are stored. + +### name + +MongoDB database name. + +> Defaults to: `"garbage_api"` + +### host + +MongoDB database host. + +> Defaults to: `"127.0.0.1"` + +### port + +MongoDB database port. + +> Defaults to: `27017` + +### user + +MongoDB database user. Can be string or `null`. + +> Defaults to: `null` + +### password + +MongoDB database password. Can be string or `null`. + +> Defaults to: `null` diff --git a/docs/api/daemonizing.md b/docs/api/daemonizing.md new file mode 100644 index 0000000..aa59cc3 --- /dev/null +++ b/docs/api/daemonizing.md @@ -0,0 +1,3 @@ +# Daemonizing + +This section is under construction. diff --git a/docs/api/feeding-data.md b/docs/api/feeding-data.md new file mode 100644 index 0000000..942ffe3 --- /dev/null +++ b/docs/api/feeding-data.md @@ -0,0 +1,3 @@ +# Feeding the API with data + +Not implemented yet. diff --git a/docs/api/index.md b/docs/api/index.md index 5932792..864f338 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1 +1,3 @@ # API + +This section is under construction. diff --git a/docs/api/installation.md b/docs/api/installation.md index e69de29..f8b98ba 100644 --- a/docs/api/installation.md +++ b/docs/api/installation.md @@ -0,0 +1,125 @@ +# Installation + +## Requirements + +* [Git](https://git-scm.com) +* [MongoDB](https://www.mongodb.com) +* [Python 3.8+](https://www.python.org) + +## Installation process + +This manual assumes that your default Python interpreter is called `python` and is Python 3 of the compatible version. + +??? question "What Python interpreter do I use?" + + Python may have multiple instances installed on your machine. + On some Linux machines Python 2.7 is the default interpreter called `python` + and Python 3 is called `python3` or `python39`. + + You can check which Python version you use using following methods: + + === "Linux" + + Check which interpreter is used: + + ``` sh title="Shell" + which python + ``` + + and check the Python version: + + ``` sh title="Shell" + python -V + ``` + + You can also change default python as follows: + + ``` sh title="Shell" + sudo update-alternatives --config python + ``` + + === "Windows" + + Check which interpreters are available: + + ``` sh title="Terminal" + where python + ``` + + and check the Python version used by default: + + ``` sh title="Terminal" + python -V + ``` + + You can also change default python using [this guide](https://stackoverflow.com/a/68139696). + + Next, use the interpreter of choice instead of `python` during the installation: + + ``` shell title="Shell" + /usr/local/bin/python311 -m venv .venv + ``` + + Please note that after the activation of a virtual environment, interpreter you need + already has a correct alias and is called `python` regardless of the version. + +### Install Mongo + +Please follow the [official installation manual](https://www.mongodb.com/docs/manual/installation) for that. + +### Clone the source code + +``` sh +# Clone the repository +git clone https://git.end-play.xyz/GarbageReminder/API.git +# Then go the repository's directory +cd API +``` + +### Create virtual environment + +=== "Linux" + + Create virtual environment and activate it: + + ``` powershell title="Shell" + python -m pip install virtualenv + virtualenv .venv + .venv/bin/activate + ``` + +=== "Windows" + + Create virtual environment and activate it: + + ``` powershell title="Terminal" + python -m pip install virtualenv + virtualenv .venv + .venv\Scripts\Activate.ps1 + ``` + +### Install the requirements + +``` sh +python -m pip install -r requirements.txt +``` + +### Configure the API server + +This is a minimal configuration needed for the first start. For more config keys visit the [configuration](api/configuration.md) section in the documentation. + +1. Copy file example to the config file + + ``` sh + cp config_example.json config.json + ``` + +2. Open `config.json` with your favorite text editor +3. Change keys in the `"database"` section to match your MongoDB setup + +### Start the API server + +You can run your API by the following command: +`uvicorn main:app --host 127.0.0.1 --port 3000` + +Learn more about available uvicorn arguments using `uvicorn --help` diff --git a/docs/api/upgrading.md b/docs/api/upgrading.md index e69de29..d6e9acf 100644 --- a/docs/api/upgrading.md +++ b/docs/api/upgrading.md @@ -0,0 +1,11 @@ +# Upgrading the API + +This section is under construction. + +## Performing the upgrade + +This section is under construction. + +## Migrating the data + +This section is under construction. diff --git a/docs/bot_telegram/configuration.md b/docs/bot_telegram/configuration.md index e69de29..d1bb542 100644 --- a/docs/bot_telegram/configuration.md +++ b/docs/bot_telegram/configuration.md @@ -0,0 +1,3 @@ +# Telegram bot configuration + +This section is under construction. diff --git a/docs/bot_telegram/feeding-data.md b/docs/bot_telegram/feeding-data.md new file mode 100644 index 0000000..a425114 --- /dev/null +++ b/docs/bot_telegram/feeding-data.md @@ -0,0 +1,3 @@ +# Feeding the bot with data + +This section is under construction. diff --git a/docs/bot_telegram/index.md b/docs/bot_telegram/index.md index 6d4baf3..d0dcc88 100644 --- a/docs/bot_telegram/index.md +++ b/docs/bot_telegram/index.md @@ -1 +1,3 @@ # Telegram Bot + +This section is under construction. diff --git a/docs/bot_telegram/installation.md b/docs/bot_telegram/installation.md index e69de29..6dc3a8c 100644 --- a/docs/bot_telegram/installation.md +++ b/docs/bot_telegram/installation.md @@ -0,0 +1,11 @@ +# Installation + +This section is under construction. + +## Requirements + +This section is under construction. + +## Installation process + +This section is under construction. diff --git a/docs/bot_telegram/upgrading.md b/docs/bot_telegram/upgrading.md index e69de29..45b8564 100644 --- a/docs/bot_telegram/upgrading.md +++ b/docs/bot_telegram/upgrading.md @@ -0,0 +1,11 @@ +# Upgrading the bot + +This section is under construction. + +## Performing the upgrade + +This section is under construction. + +## Migrating the data + +This section is under construction. diff --git a/docs/community/contact.md b/docs/community/contact.md index e69de29..2d216cd 100644 --- a/docs/community/contact.md +++ b/docs/community/contact.md @@ -0,0 +1,3 @@ +# Get in touch + +This section is under construction. diff --git a/docs/community/contributing.md b/docs/community/contributing.md index e69de29..14e4d05 100644 --- a/docs/community/contributing.md +++ b/docs/community/contributing.md @@ -0,0 +1,3 @@ +# Contributing + +This section is under construction. diff --git a/docs/community/index.md b/docs/community/index.md index 100f4c1..6542a06 100644 --- a/docs/community/index.md +++ b/docs/community/index.md @@ -1 +1,3 @@ # Community + +This section is under construction. diff --git a/docs/community/public/entries.md b/docs/community/public/entries.md index e69de29..03e926f 100644 --- a/docs/community/public/entries.md +++ b/docs/community/public/entries.md @@ -0,0 +1,3 @@ +# Adding entries + +This section is under construction. diff --git a/docs/community/public/index.md b/docs/community/public/index.md index 48178cf..5ab0139 100644 --- a/docs/community/public/index.md +++ b/docs/community/public/index.md @@ -1 +1,3 @@ # Public instance + +This section is under construction. diff --git a/docs/community/public/locations.md b/docs/community/public/locations.md index e69de29..8413ac9 100644 --- a/docs/community/public/locations.md +++ b/docs/community/public/locations.md @@ -0,0 +1,3 @@ +# Adding locations + +This section is under construction. diff --git a/docs/community/public/report.md b/docs/community/public/report.md index e69de29..cb7102e 100644 --- a/docs/community/public/report.md +++ b/docs/community/public/report.md @@ -0,0 +1,3 @@ +# Report a problem + +This section is under construction. diff --git a/docs/community/report-bug.md b/docs/community/report-bug.md index e69de29..cae7096 100644 --- a/docs/community/report-bug.md +++ b/docs/community/report-bug.md @@ -0,0 +1,3 @@ +# Reporting a bug + +This section is under construction. diff --git a/docs/community/translate.md b/docs/community/translate.md index e69de29..5bea676 100644 --- a/docs/community/translate.md +++ b/docs/community/translate.md @@ -0,0 +1,3 @@ +# Adding translations + +This section is under construction. diff --git a/docs/index.md b/docs/index.md index a6d7f43..c50151d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,3 +1,27 @@ # Welcome to Garbage Reminder -This documentation is under development and is not finished yet. +Universal, easy to set up and maintain way to remind your family, your neighbors or your tenants about garbage collection. +Built with Python using FastAPI, Pyrogram, MkDocs Material and in the future also Pycord. + +## How it works + +The whole instance consist of an API and the clients. +We provide chatbots as clients. These bots provide the access to the data stored in the database of an API. + +## Why this exists + +After seeing that most cities and villages around only offer proprietary software/websites or even no digital information +about garbage collection at all, it was decided to develop an own solution to this problem by storing the data in a +database and then show the data the way it is helpful for the end-user. + +## Deployment + +Bare minimum installation requires a database and an API. Then you can use any way you like to connect to the API. +We provide Telegram bot and raw HTTP for that now, but Discord bot and CLI are planned too. + +Here is how the "normal" deployment process looks like: + +1. Install the requirements [[API](api/installation.md#requirements)/[Telegram](bot_telegram/installation.md#requirements)] +2. Install the API server [[Guide](api/installation.md)] +3. Install the client/bot of your linking [[Telegram](bot_telegram/installation.md)] +4. Fill the API/bot with the data [[API](api/feeding-data.md)/[Telegram](bot_telegram/feeding-data.md)] diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index 1ef4420..82be0df 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -2,4 +2,7 @@ --md-primary-fg-color: #A9C217; --md-primary-fg-color--light: #A9C217; --md-primary-fg-color--dark: #A9C217; + --md-accent-fg-color: #bedd0e; + --md-accent-fg-color--light: #bedd0e; + --md-accent-fg-color--dark: #bedd0e; } \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 9d6a54b..f1e8b84 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,11 +7,14 @@ nav: - api/index.md - Installation: api/installation.md - Configuration: api/configuration.md + - Daemonizing: api/daemonizing.md + - Feeding data: api/feeding-data.md - Upgrading: api/upgrading.md - Telegram Bot: - bot_telegram/index.md - Installation: bot_telegram/installation.md - Configuration: bot_telegram/configuration.md + - Feeding data: bot_telegram/feeding-data.md - Upgrading: bot_telegram/upgrading.md - Community: - community/index.md @@ -91,4 +94,11 @@ theme: text: Roboto code: Roboto Mono icon: - logo: logo \ No newline at end of file + logo: logo +markdown_extensions: + - pymdownx.details + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - toc: + permalink: true \ No newline at end of file