Placeholders and README #2
17
README.md
17
README.md
@ -1,3 +1,18 @@
|
|||||||
# Garbage Reminder Documentation
|
# 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`
|
||||||
|
@ -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`
|
3
docs/api/daemonizing.md
Normal file
3
docs/api/daemonizing.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
# Daemonizing
|
||||||
|
|
||||||
|
This section is under construction.
|
3
docs/api/feeding-data.md
Normal file
3
docs/api/feeding-data.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
# Feeding the API with data
|
||||||
|
|
||||||
|
Not implemented yet.
|
@ -1 +1,3 @@
|
|||||||
# API
|
# API
|
||||||
|
|
||||||
|
This section is under construction.
|
||||||
|
@ -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`
|
@ -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.
|
@ -0,0 +1,3 @@
|
|||||||
|
# Telegram bot configuration
|
||||||
|
|
||||||
|
This section is under construction.
|
3
docs/bot_telegram/feeding-data.md
Normal file
3
docs/bot_telegram/feeding-data.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
# Feeding the bot with data
|
||||||
|
|
||||||
|
This section is under construction.
|
@ -1 +1,3 @@
|
|||||||
# Telegram Bot
|
# Telegram Bot
|
||||||
|
|
||||||
|
This section is under construction.
|
||||||
|
@ -0,0 +1,11 @@
|
|||||||
|
# Installation
|
||||||
|
|
||||||
|
This section is under construction.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
This section is under construction.
|
||||||
|
|
||||||
|
## Installation process
|
||||||
|
|
||||||
|
This section is under construction.
|
@ -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.
|
@ -0,0 +1,3 @@
|
|||||||
|
# Get in touch
|
||||||
|
|
||||||
|
This section is under construction.
|
@ -0,0 +1,3 @@
|
|||||||
|
# Contributing
|
||||||
|
|
||||||
|
This section is under construction.
|
@ -1 +1,3 @@
|
|||||||
# Community
|
# Community
|
||||||
|
|
||||||
|
This section is under construction.
|
||||||
|
@ -0,0 +1,3 @@
|
|||||||
|
# Adding entries
|
||||||
|
|
||||||
|
This section is under construction.
|
@ -1 +1,3 @@
|
|||||||
# Public instance
|
# Public instance
|
||||||
|
|
||||||
|
This section is under construction.
|
||||||
|
@ -0,0 +1,3 @@
|
|||||||
|
# Adding locations
|
||||||
|
|
||||||
|
This section is under construction.
|
@ -0,0 +1,3 @@
|
|||||||
|
# Report a problem
|
||||||
|
|
||||||
|
This section is under construction.
|
@ -0,0 +1,3 @@
|
|||||||
|
# Reporting a bug
|
||||||
|
|
||||||
|
This section is under construction.
|
@ -0,0 +1,3 @@
|
|||||||
|
# Adding translations
|
||||||
|
|
||||||
|
This section is under construction.
|
@ -1,3 +1,27 @@
|
|||||||
# Welcome to Garbage Reminder
|
# 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)]
|
||||||
|
@ -2,4 +2,7 @@
|
|||||||
--md-primary-fg-color: #A9C217;
|
--md-primary-fg-color: #A9C217;
|
||||||
--md-primary-fg-color--light: #A9C217;
|
--md-primary-fg-color--light: #A9C217;
|
||||||
--md-primary-fg-color--dark: #A9C217;
|
--md-primary-fg-color--dark: #A9C217;
|
||||||
|
--md-accent-fg-color: #bedd0e;
|
||||||
|
--md-accent-fg-color--light: #bedd0e;
|
||||||
|
--md-accent-fg-color--dark: #bedd0e;
|
||||||
}
|
}
|
10
mkdocs.yml
10
mkdocs.yml
@ -7,11 +7,14 @@ nav:
|
|||||||
- api/index.md
|
- api/index.md
|
||||||
- Installation: api/installation.md
|
- Installation: api/installation.md
|
||||||
- Configuration: api/configuration.md
|
- Configuration: api/configuration.md
|
||||||
|
- Daemonizing: api/daemonizing.md
|
||||||
|
- Feeding data: api/feeding-data.md
|
||||||
- Upgrading: api/upgrading.md
|
- Upgrading: api/upgrading.md
|
||||||
- Telegram Bot:
|
- Telegram Bot:
|
||||||
- bot_telegram/index.md
|
- bot_telegram/index.md
|
||||||
- Installation: bot_telegram/installation.md
|
- Installation: bot_telegram/installation.md
|
||||||
- Configuration: bot_telegram/configuration.md
|
- Configuration: bot_telegram/configuration.md
|
||||||
|
- Feeding data: bot_telegram/feeding-data.md
|
||||||
- Upgrading: bot_telegram/upgrading.md
|
- Upgrading: bot_telegram/upgrading.md
|
||||||
- Community:
|
- Community:
|
||||||
- community/index.md
|
- community/index.md
|
||||||
@ -92,3 +95,10 @@ theme:
|
|||||||
code: Roboto Mono
|
code: Roboto Mono
|
||||||
icon:
|
icon:
|
||||||
logo: logo
|
logo: logo
|
||||||
|
markdown_extensions:
|
||||||
|
- pymdownx.details
|
||||||
|
- pymdownx.superfences
|
||||||
|
- pymdownx.tabbed:
|
||||||
|
alternate_style: true
|
||||||
|
- toc:
|
||||||
|
permalink: true
|
Loading…
Reference in New Issue
Block a user