Merge pull request #7 from aosus/create-docs

Create docs

.github/workflows/mkdocs-build.yml

@@ -0,0 +1,87 @@
+name: Build Docs
+
+on:
+  workflow_dispatch:
+  push:
+    paths: 
+      - 'docs/**'
+      - '.github/workflows/mkdocs-build.yml'
+      - 'docs/requirements.txt'
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+    paths: 
+      - 'docs/**'
+      - '.github/workflows/mkdocs-build.yml'
+      - 'docs/requirements.txt'
+  pull_request_review:
+    types: [edited, dismissed]
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      deployments: write
+
+    steps:
+    - name: Checkout 🛎️
+      uses: actions/checkout@v3 
+      with:
+        persist-credentials: false
+        fetch-depth: '0'
+
+    # setup python
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.11.*
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip setuptools
+        python -m pip install -U pip wheel
+        python -m pip install -r docs/requirements.txt
+        pip show mkdocs-material
+
+    - name: mkdocs build
+      run: mkdocs build -f docs/mkdocs.yml --clean --verbose -d generated
+
+    - name: Include _headers file
+      run: cp docs/_headers docs/generated/_headers
+
+    - name: Publish to Cloudflare Pages
+      if: github.event_name != 'pull_request'
+      uses: cloudflare/pages-action@1
+      with:
+        apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        accountId: ${{ secrets.CLOUDFLARE_ID }}
+        projectName: ${{ secrets.CLOUDFLARE_PROJECT_NAME }}
+        directory: docs/generated
+        gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+        branch: main
+
+    - name: Publish preview to Cloudflare Pages
+      if: github.event_name == 'pull_request'
+      uses: cloudflare/pages-action@1
+      with:
+        apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        accountId: ${{ secrets.CLOUDFLARE_ID }}
+        projectName: ${{ secrets.CLOUDFLARE_PROJECT_NAME }}
+        directory: docs/generated
+        gitHubToken: ${{ secrets.GITHUB_TOKEN }}
+        branch: ${{ github.ref.name }}
+
+    - name: Cache pip files
+      uses: actions/cache@v3.0.11
+      env:
+        cache-name: pip-reg
+      with:
+        path: $HOME/.cache/pip
+        key: pip-reg
+
+    - name: Cache Mkdocs files
+      uses: actions/cache@v3
+      with:
+        key: ${{ github.ref }}
+        path: .cache

docs/_headers

@@ -0,0 +1,2 @@
+https://:project.pages.dev/*
+  X-Robots-Tag: noindex

docs/mkdocs.yml

@@ -0,0 +1,86 @@
+site_name: Discourse chat bridge
+site_url: https://discourse-chat-bridge.aosus.dev
+repo_name: aosus/discourse-chat-bridge
+repo_url: https://github.com/aosus/discourse-chat-bridge
+edit_uri: https://github.com/aosus/discourse-chat-bridge/docs
+site_description: A chat bridge allowing users to post, reply and interact with discourse posts from their own favorite chat platforms.
+docs_dir: source
+
+plugins:
+  - autolinks
+  - search
+  - git-revision-date-localized:
+      type: timeago
+  - minify:
+      minify_html: true
+
+theme: 
+  name: material
+  custom_dir: overrides
+  logo: images/Discourse_Bridge.webp
+  icon:
+    repo: fontawesome/brands/github
+  font: false
+  features:
+    - search.suggest 
+    - search.highlight
+    - content.tabs.link
+    - navigation.instant
+    - navigation.tracking
+    - toc.integrate
+  palette:
+  # Palette toggle for light mode
+  - media: "(prefers-color-scheme: light)"
+    scheme: default
+    toggle:
+      icon: material/brightness-7
+      name: Switch to dark mode
+    primary: green
+    accent: blue
+
+  # Palette toggle for dark mode
+  - media: "(prefers-color-scheme: dark)"
+    scheme: slate
+    toggle:
+      icon: material/brightness-4
+      name: Switch to light mode
+    primary: green
+    accent: blue
+
+
+extra:
+  alternate:
+    - name: English
+      link: /
+      lang: en
+
+    - name: العربية
+      link: /ar/ 
+      lang: ar
+
+  social:
+    - icon: fontawesome/brands/github
+      link: https://github.com/aosus
+    - icon: fontawesome/brands/twitter
+      link: https://twitter.com/aosusorg
+    - icon: fontawesome/brands/mastodon
+      link: https://mastodon.online/@aosus
+    - icon: fontawesome/brands/telegram
+      link: https://t.me/aosus
+    - icon: matrix
+      link: https://matrix.to/#/#aosus:aosus.org
+    - icon: fontawesome/brands/linkedin
+      link: https://www.linkedin.com/company/aosus/
+
+markdown_extensions:
+  - admonition
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+
+extra_css:
+  - extra.css

docs/overrides/extra.css

@@ -0,0 +1,5 @@
+@import url("https://aosus.org/fonts/fonts.css");
+
+:root {
+  --md-text-font: "Almarai"; 
+}

docs/overrides/main.html

@@ -0,0 +1,5 @@
+{% extends "base.html" %}
+
+{% block analytics %}
+    <script defer data-domain="discourse-chat-bridge.aosus.dev" src="https://pa.aosus.org/js/pls4.js"></script>
+{% endblock %}

docs/requirements.txt

@@ -0,0 +1,6 @@
+mkdocs
+mkdocs-material
+git+https://github.com/midnightprioriem/mkdocs-autolinks-plugin
+mkdocs-git-revision-date-localized-plugin
+mkdocs-minify-plugin
+Pygments

docs/source/index.md

@@ -0,0 +1,25 @@
+# Discourse-chat-bridge
+<div style="text-align: center;">
+  <img src="images/Discourse_Bridge.webp" alt="discourse-chat-bridge" />
+  <p>A chat bridge allowing users to post, reply and interact with discourse posts from their own favorite chat platforms.</p>
+  <a href="installation" class="md-button md-button--primary">Installation</a>
+</div>
+
+## Bridge Features
+
+- fetch the latest published topic 📄
+- fetch categories ⬇️
+- Post a new topic 📝
+- Post a new comment 💬
+- Send a private message 🔒
+- Link your chat account with your discussion account
+- Receive the latest topics posted from the bot
+
+## Supported platforms
+- Matrix
+- Telegram
+
+## License
+Discourse-chat-bridge is licensed under the AGPLv3.
+
+![license](https://www.gnu.org/graphics/agplv3-with-text-162x68.png)

docs/source/installation.md

@@ -0,0 +1,71 @@
+# Installation
+
+## Discourse setup
+Go to Admin Settings > API and create a new API key.
+It should have a granular scope and be able to access all users.
+Make sure you also give the token topics write access.
+
+![Api settings](images/api-setup.png)
+
+### installation with docker-compose.yml
+```yaml
+services:
+    discourse-chat-bridge:
+        image: oci.aosus.org/aosus/discourse-chat-bridge:latest
+        restart: always
+        environment:
+            URL: "https://discourse.example.com"
+            DISCOURSE_FORUM_NAME: "Discourse community"
+            DISCOURSE_TOKEN: "API key with write access for all users"
+            DISCOURSE_USERNAME: "username to be used for Direct messages from the bridge"
+            TELEGRAM_TOKEN: ""
+            MATRIX_USERNAME: ""
+            #MATRIX_PASSWORD: "" matrix password shouldn't beused in env variables, rather you should directly set the access token.
+            MATRIX_HOMESERVER_URL: "https://matrix.example.com"
+            MATRIX_ACCESS_TOKEN: ""
+            MATRIX_AUTOJOIN: TRUE
+            DATAPATH: /data
+            MATRIX_ENCRYPTION: TRUE
+            language: "en"
+        volumes:
+            ./data:/data:rw:z
+```
+
+Then you can start the container
+```bash
+docker compose up -d
+```
+
+## Native
+```bash
+git clone https://github.com/aosus/discourse-chat-bridge
+```
+
+edit `config.json` and add required inputs
+```json
+{
+	"url": "https://$DISCOURSE_DOMAIN",
+	"discourse_forum_name": "discourse forum name",
+	"discourse_token": "API key with write access for all users",
+	"discourse_username": "username to be used for Direct messages from the bridge",
+	"telegram_token": "",
+	"matrix_username": "Username to your Matrix account #aosus",
+	"matrix_password": "Password to your Matrix account to generate the access token, you can skip this by inputing it directly",
+	"matrix_homeserver_url": "https://matrix.org",
+	"matrix_access_token": "Put your matrix_access_token here #npm run generate_matrix_token",
+	"matrix_autojoin": true,
+	"dataPath": "./storage",
+	"matrix_encryption": true,
+	"language": "en"
+}
+```
+
+Then start it up!
+
+```bash
+npm i
+npm run generate_matrix_token
+npm start
+or
+node index.js
+```

docs/source/usage.md

@@ -0,0 +1,14 @@
+# Usage
+
+## Bot commands
+
+|  Command  | description|
+|:--------------|-----------------:|
+| start | Start the bot |
+| discourse | Link your Discourse account |
+| get_latest_posts | Fetch and display the latest posts |
+| getCategories | 	List available categories |
+| CreatePosts | 	Create a new post |
+| sendComment | Send a comment on an existing post |
+| sendMessagePrivate | 	Send a private message |
+| activation | 	Activate notifications for new posts |

docs/source/عربي/index.md

@@ -0,0 +1,27 @@
+# الرئيسية
+<div style="text-align: center;">
+  <img src="/images/Discourse_Bridge.webp" alt="discourse-chat-bridge" />
+  <p>جسر بين منصة Discourse وبرامج التواصل .
+</p>
+  <a href="installation" class="md-button md-button--primary">تثبيت</a>
+</div>
+
+- تيليجرام - مدعوم
+- matrix - مدعوم
+
+# مميزات الجسر
+
+- عرض آخر موضوع تم نشره 📄
+- عرض الفئات ⬇️
+- كتابة موضوع جديد 📝
+- كتابة تعليق جديد 💬
+- إرسال رسالة خاصة 🔒
+- ربط حسابك على منصة Discourse 
+- تفعيل البوت لتلقي آخر المواضيع المنشورة
+
+
+
+## الترخيص
+مرخص تحت AGPLv3.
+
+![license](https://www.gnu.org/graphics/agplv3-with-text-162x68.png)