Placeholders and README #2

Merged
profitroll merged 4 commits from dev into main 2024-05-14 00:43:12 +03:00
24 changed files with 292 additions and 3 deletions

View File

@ -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`

View File

@ -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
View File

@ -0,0 +1,3 @@
# Daemonizing
This section is under construction.

3
docs/api/feeding-data.md Normal file
View File

@ -0,0 +1,3 @@
# Feeding the API with data
Not implemented yet.

View File

@ -1 +1,3 @@
# API
This section is under construction.

View File

@ -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`

View File

@ -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.

View File

@ -0,0 +1,3 @@
# Telegram bot configuration
This section is under construction.

View File

@ -0,0 +1,3 @@
# Feeding the bot with data
This section is under construction.

View File

@ -1 +1,3 @@
# Telegram Bot
This section is under construction.

View File

@ -0,0 +1,11 @@
# Installation
This section is under construction.
## Requirements
This section is under construction.
## Installation process
This section is under construction.

View File

@ -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.

View File

@ -0,0 +1,3 @@
# Get in touch
This section is under construction.

View File

@ -0,0 +1,3 @@
# Contributing
This section is under construction.

View File

@ -1 +1,3 @@
# Community
This section is under construction.

View File

@ -0,0 +1,3 @@
# Adding entries
This section is under construction.

View File

@ -1 +1,3 @@
# Public instance
This section is under construction.

View File

@ -0,0 +1,3 @@
# Adding locations
This section is under construction.

View File

@ -0,0 +1,3 @@
# Report a problem
This section is under construction.

View File

@ -0,0 +1,3 @@
# Reporting a bug
This section is under construction.

View File

@ -0,0 +1,3 @@
# Adding translations
This section is under construction.

View File

@ -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)]

View File

@ -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;
}

View File

@ -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
@ -92,3 +95,10 @@ theme:
code: Roboto Mono
icon:
logo: logo
markdown_extensions:
- pymdownx.details
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
- toc:
permalink: true