Merge pull request 'Placeholders and README' (#2) from dev into main

Reviewed-on: #2

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`

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`

docs/api/daemonizing.md

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

docs/api/feeding-data.md

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

docs/api/index.md

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

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`

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.

docs/bot_telegram/configuration.md

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

docs/bot_telegram/feeding-data.md

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

docs/bot_telegram/index.md

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

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.

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.

docs/community/contact.md

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

docs/community/contributing.md

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

docs/community/index.md

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

docs/community/public/entries.md

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

docs/community/public/index.md

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

docs/community/public/locations.md

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

docs/community/public/report.md

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

docs/community/report-bug.md

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

docs/community/translate.md

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

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

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

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