civictechdc · KristijanArmeni · May 9, 2025 · May 9, 2025 · May 9, 2025 · May 15, 2025
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,71 @@
+# see: https://github.com/marketplace/actions/deploy-mkdocs
+name: Publish docs via GitHub Pages
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      deploy_to:
+        description: 'Deployment destination'
+        type: choice
+        options:
+          - prod
+          - preview
+
+
+permissions:
+  contents: write
+  deployments: write
+  pages: write
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          # ✅ Explicitly checkout the PR branch
+          ref: ${{ github.event.pull_request.head.sha }}
+      - name: Build
+        uses: Tiryoh/actions-mkdocs@v0.24.0
+        if: github.event.action != 'closed'
+        with:
+          # mkdocs_version: 'latest' # option
+          #mkdocs_version: '1.1' # option
+          requirements: 'requirements-mkdocs.txt' # option
+          configfile: 'mkdocs.yml' # option
+      - uses: rossjrw/pr-preview-action@v1
+        if: github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && inputs.deploy_to == 'preview')
+        with:
+          source-dir: site/
+          preview-branch: gh-pages
+          umbrella-dir: pr-preview
+          action: auto
+      - uses: JamesIves/github-pages-deploy-action@v4
+        if: (github.event_name == 'push' && github.ref_name == 'main') ||  (github.event_name == 'workflow_dispatch' && inputs.deploy_to == 'prod')
+        with:
+          folder: site/
+          branch: gh-pages
+          clean-exclude: pr-preview
+          force: false
+
+      # - name: Deploy docs
+      #   uses: mhausenblas/mkdocs-deploy-gh-pages@master
+      #   # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
+      #   env:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #     #CUSTOM_DOMAIN: optionaldomain.com
+      #     CONFIG_FILE: mkdocs.yml
+      #     EXTRA_PACKAGES: build-base
+      #     # GITHUB_DOMAIN: github.myenterprise.com
+      #     REQUIREMENTS: requirements-mkdocs.txt
diff --git a/README.md b/README.md
@@ -1,4 +1,17 @@
-# mango-tango-cli: A python terminal wrapper for CIB Mango Tree analyzers
+<h2 align="center">mango-tango-cli</h2>
+<h3 align="center">A Python command-line tool for detecting coordinated inauthentic behavior</h3>
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/CIB-Mango-Tree/CIB-Mango-Tree-Website/main/assets/images/mango-text.PNG" alt="Mango logo" style="width:200px;"/>
+</p>
+
+<p align="center">
+<a href="https://www.python.org/"><img alt="code" src="https://img.shields.io/badge/code-Python%203.12-blue?logo=Python"></a>
+<a href="https://black.readthedocs.io/en/stable/"><img alt="style: black" src="https://img.shields.io/badge/style-Black-black?logo=Black"></a>
+<a href="https://docs.astral.sh/ruff/"><img alt="style: black" src="https://img.shields.io/badge/tool-Polars-skyblue?logo=Polars"></a>
+</p>
+
+---
 
 ## Requirements
 

diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md
@@ -0,0 +1,46 @@
+# Contributor Workflow
+
+## Overview
+All changes should be made in a feature branch, merged into `develop`, and later merged into `main` for a new release.
+
+## Seting up your development environment
+
+Coming soon!
+
+## Contributing new changes
+1. **Create a Feature Branch**
+   - Branch from `develop` using `feature/<name>` or `bugfix/<name>`.
+   - Example:
+     ```bash
+     git checkout develop
+     git pull origin develop
+     git checkout -b feature/new-feature
+     ```
+
+2. **Make Changes & Push**
+   - Commit changes with clear messages.
+   - Push the branch.
+     ```bash
+     git add .
+     git commit -m "Description of changes"
+     git push origin feature/new-feature
+     ```
+
+3. **Create a Pull Request**
+   - Open a PR to merge into `develop`.
+   - Address any review feedback.
+
+4. **Merge & Clean Up**
+   - After approval, merge into `develop`.
+   - Delete the feature branch.
+
+5. **Release**
+   - When develop is clean and ready for a new major release, we will merge `develop` into `main`.
+
+## Workflow Diagram
+```mermaid
+graph TD;
+    A[Feature Branch] -->|Commit & Push| B[Pull Request];
+    B -->|Review & Merge| C[Develop Branch];
+    C -->|Release| D[Main Branch];
+```
diff --git a/docs/dev-guide.md → docs/guides/dev-guide.md b/docs/dev-guide.md → docs/guides/dev-guide.md
@@ -1,4 +1,3 @@
-# CIB 🥭 Development Guide
 Before contributing please refer to our [**Contributor Workflow**](#contributor-workflow)
 
 ## Application Design Overview
@@ -118,53 +117,6 @@ workable example.
 The `testing` module provides testers for the primary and
 secondary analyzer modules. See the [example](../analyzers/example/README.md) for further references.
 
-# Contributor Workflow
-
-## Overview
-All changes should be made in a feature branch, merged into `develop`, and later merged into `main` for a new release.
-
-## Steps
-1. **Create a Feature Branch**
-   - Branch from `develop` using `feature/<name>` or `bugfix/<name>`.
-   - Example:
-     ```bash
-     git checkout develop
-     git pull origin develop
-     git checkout -b feature/new-feature
-     ```
-
-2. **Make Changes & Push**
-   - Commit changes with clear messages.
-   - Push the branch.
-     ```bash
-     git add .
-     git commit -m "Description of changes"
-     git push origin feature/new-feature
-     ```
-
-3. **Create a Pull Request**
-   - Open a PR to merge into `develop`.
-   - Address any review feedback.
-
-4. **Merge & Clean Up**
-   - After approval, merge into `develop`.
-   - Delete the feature branch.
-
-5. **Release**
-   - When develop is clean and ready for a new major release, we will merge `develop` into `main`.
-
-## Workflow Diagram
-```mermaid
-graph TD;
-    A[Feature Branch] -->|Commit & Push| B[Pull Request];
-    B -->|Review & Merge| C[Develop Branch];
-    C -->|Release| D[Main Branch];
-```
-
-
-
-
-
 # Questions, Comments, and Feedback
 
 Talk to us on the [Civic Tech DC Slack workspace](https://civictechdc.slack.com)!

diff --git a/docs/guides/get-started.md b/docs/guides/get-started.md
@@ -0,0 +1,104 @@
+# Getting Started
+
+## Requirements
+- Python (3.12)
+- Node.JS (20.0.0 or above)
+- Git (latest version)
+
+## Setting up
+If you haven't installed git, node.js, and python yet refer to the following links to start installing said packages:
+- [https://codefinity.com/blog/A-step-by-step-guide-to-Git-installation](https://codefinity.com/blog/A-step-by-step-guide-to-Git-installation)
+- [https://nodejs.org/en/download](https://nodejs.org/en/download)
+- [https://realpython.com/installing-python/](https://realpython.com/installing-python/)
+
+If you're not sure which packages you already have installed on your system, the following commands can be used to figure what packages you already installed:
+
+#### Linux & Mac OS
+```shell
+which <program_name_here>
+```
+
+#### Windows
+```shell
+where.exe python
+```
+
+## Setting Up Environment
+Next step is to create the virtual environment at `venv` using the following command
+
+```shell
+python -m venv venv
+```
+
+Once the virtual environment with `venv` is created the next can be used to active the environment
+
+- Activate the virtual environment after creating the `venv` directory:
+  - Bash (Linux / Mac OS): `source ./venv/bin/activate`
+  - PS1 (Windows): `./env/bin/Activate.ps1`
+
+
+- Run the bootstrap script for your shell environment:
+  - Bash (Linux / Mac OS): `./bootstrap.sh`
+  - PS1 (Windows): `./bootstrap.ps1`
+
+This will install the required dependencies for project development.
+
+## Starting Services
+
+### Starting CLI App
+```shell
+python -m mangotango
+```
+
+### Starting the Development Server for The Dashboards
+```shell
+cd ./app/web_templates
+npm run dev
+```
+
+It should be noted that running the development server is only required if you're working on the dashboard while debug mode is enabled for the CLI app web server. Setting the environment variable `FLASK_DEBUG` to `1` in your shell environment is enough to put the server into debug mode. For example:
+
+#### Linux & Mac OS
+```shell
+export FLASK_DEBUG=1
+```
+
+#### Windows
+```shell
+$env:FLASK_DEBUG = "1"
+```
+
+## Version Management
+If you already have Python and Node.JS installed but are on different versions from the versions outlined in the [requirements](#requirements) above you can switch to the correct versions for both languages for the project using version managers. The version manager for python is [pyenv](https://github.com/pyenv/pyenv). Where the version manager that is recommended for Node is [nvm](https://github.com/nvm-sh/nvm). Guides for installing both version managers are linked down below if you need references to go off of
+
+- [https://www.freecodecamp.org/news/node-version-manager-nvm-install-guide/](https://www.freecodecamp.org/news/node-version-manager-nvm-install-guide/)
+- [https://github.com/pyenv/pyenv?tab=readme-ov-file#installation](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation)
+- [https://github.com/pyenv-win/pyenv-win?tab=readme-ov-file#installation](https://github.com/pyenv-win/pyenv-win?tab=readme-ov-file#installation)(If you're on windows and want to install pyenv)
+
+Once you have both version managers installed the following commands can be used to switch versions
+
+### pyenv
+```shell
+pyenv install 3.12
+pyenv local 3.12
+```
+
+### nvm
+```shell
+nvm install v21.0.0
+nvm use v21.0.0
+```
+
+## Common Dependency Issues
+One common issue when installing the dependencies for python is the installation failing due to compatibility issues with the python package `pyarrow`. The compatibility issues are due to a version mismatch between pyarrow any python itself. To resolve this issue, you MUST be on version 3.12 for python. Refer to [commands above](#pyenv) to switch to the correct version.
+
+Similarly, the installation for node dependencies has been known to fail for some developers due to a version mismatch caused by the underlying dependencies for the package `@glideapps/glide-data-grid`. However, getting around this issue is more straightforward with node packages. Running the installation command for node with the flag `--legacy-peer-deps` is enough for the installation to work if you run into this issue. The commands needed to run the installation manually are as such.
+
+```shell
+cd ./app/web_templates
+npm install --legacy-peer-deps
+```
+
+
+# Next Steps
+Once you have everything installed and running without any problems, the next step is to check out the [Contributor Workflow](./contributing.md)
diff --git a/docs/img/favicon.ico b/docs/img/favicon.ico
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,5 @@
+# CIB Mango Tree Technical documentation
+
+Welcome to the technical documentation website of 🥭 [CIB Mango Tree](https://www.cibmangotree.org) 🥭, a collaborative and open-source project to develop software that tests for coordinated inauthentic behavior (CIB) in datasets of online activity. 
+
+This is the technical documentation, for a user-based perspective and project story see: [www.cibmangotree.org](https://www.cibmangotree.org)
diff --git a/docs/license.md b/docs/license.md
@@ -0,0 +1,9 @@
+---
+title: License
+hide:
+- feedback
+---
+
+```
+--8<-- "LICENSE"
+```
diff --git a/docs/reference/analyzer_interface.md b/docs/reference/analyzer_interface.md
@@ -0,0 +1,3 @@
+:::analyzer_interface
+    options:
+        show_submodules: true
diff --git a/docs/reference/app.md b/docs/reference/app.md
@@ -0,0 +1,3 @@
+:::app
+    options:
+        show_submodules: true
diff --git a/docs/reference/components.md b/docs/reference/components.md
@@ -0,0 +1,3 @@
+:::components
+    options:
+        show_submodules: true
diff --git a/docs/reference/importing.md b/docs/reference/importing.md
@@ -0,0 +1,3 @@
+:::importing
+    options:
+        show_submodules: true
diff --git a/docs/reference/meta.md b/docs/reference/meta.md
@@ -0,0 +1,3 @@
+:::meta
+    options:
+        show_submodules: true
diff --git a/docs/reference/preprocessing.md b/docs/reference/preprocessing.md
@@ -0,0 +1,3 @@
+:::preprocessing
+    options:
+        show_submodules: true
diff --git a/docs/reference/storage.md b/docs/reference/storage.md
@@ -0,0 +1,3 @@
+:::storage
+    options:
+        show_submodules: true
diff --git a/docs/reference/terminal_tools.md b/docs/reference/terminal_tools.md
@@ -0,0 +1,5 @@
+# Terminal tools
+
+:::terminal_tools
+    options:
+        show_submodules: true
diff --git a/docs/reference/testing.md b/docs/reference/testing.md
@@ -0,0 +1,3 @@
+:::testing
+    options:
+        show_submodules: true