Placeholders and README #2
17
README.md
17
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`
|
||||
|
@ -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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
This section is under construction.
|
||||
|
@ -0,0 +1,3 @@
|
||||
# Adding entries
|
||||
|
||||
This section is under construction.
|
@ -1 +1,3 @@
|
||||
# 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
|
||||
|
||||
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--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;
|
||||
}
|
12
mkdocs.yml
12
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
|
||||
logo: logo
|
||||
markdown_extensions:
|
||||
- pymdownx.details
|
||||
- pymdownx.superfences
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- toc:
|
||||
permalink: true
|
Loading…
Reference in New Issue
Block a user