From ebe4c97742828c4e84972536e85296ed53b4f00d Mon Sep 17 00:00:00 2001 From: Kristijan Armeni Date: Fri, 9 May 2025 11:59:18 -0400 Subject: [PATCH 01/18] add mkdocs config and populate /docs folder --- docs/img/favicon.ico | Bin 0 -> 3614 bytes docs/index.md | 5 +++ docs/license.md | 9 +++++ docs/reference/analyzer_interface.md | 3 ++ docs/reference/app.md | 3 ++ docs/reference/components.md | 3 ++ docs/reference/importing.md | 3 ++ docs/reference/meta.md | 3 ++ docs/reference/preprocessing.md | 3 ++ docs/reference/storage.md | 3 ++ docs/reference/terminal_tools.md | 5 +++ docs/reference/testing.md | 3 ++ mkdocs.yml | 56 +++++++++++++++++++++++++++ 13 files changed, 99 insertions(+) create mode 100644 docs/img/favicon.ico create mode 100644 docs/index.md create mode 100644 docs/license.md create mode 100644 docs/reference/analyzer_interface.md create mode 100644 docs/reference/app.md create mode 100644 docs/reference/components.md create mode 100644 docs/reference/importing.md create mode 100644 docs/reference/meta.md create mode 100644 docs/reference/preprocessing.md create mode 100644 docs/reference/storage.md create mode 100644 docs/reference/terminal_tools.md create mode 100644 docs/reference/testing.md create mode 100644 mkdocs.yml diff --git a/docs/img/favicon.ico b/docs/img/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..297134257625be69c1593fb5f284e0bc3f129320 GIT binary patch literal 3614 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 literal 0 HcmV?d00001 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..643748be --- /dev/null +++ b/docs/index.md @@ -0,0 +1,5 @@ +# CIB Mango Tree Technical documentation + +Welcome to the technical documentation website of 🥭 [CIB Mango Tree](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 technical documentation, for a user-based perspective and project story see: [www.cibmangotree.org](www.cibmangotree.org) \ No newline at end of file diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 00000000..3df65ec2 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,9 @@ +--- +title: License +hide: +- feedback +--- + +``` +--8<-- "LICENSE" +``` \ No newline at end of file diff --git a/docs/reference/analyzer_interface.md b/docs/reference/analyzer_interface.md new file mode 100644 index 00000000..29111a53 --- /dev/null +++ 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 new file mode 100644 index 00000000..48daaa7a --- /dev/null +++ b/docs/reference/app.md @@ -0,0 +1,3 @@ +:::app + options: + show_submodules: true \ No newline at end of file diff --git a/docs/reference/components.md b/docs/reference/components.md new file mode 100644 index 00000000..d790b8be --- /dev/null +++ b/docs/reference/components.md @@ -0,0 +1,3 @@ +:::components + options: + show_submodules: true \ No newline at end of file diff --git a/docs/reference/importing.md b/docs/reference/importing.md new file mode 100644 index 00000000..2592c016 --- /dev/null +++ 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 new file mode 100644 index 00000000..32bf08ad --- /dev/null +++ b/docs/reference/meta.md @@ -0,0 +1,3 @@ +:::meta + options: + show_submodules: true \ No newline at end of file diff --git a/docs/reference/preprocessing.md b/docs/reference/preprocessing.md new file mode 100644 index 00000000..9ddfbe50 --- /dev/null +++ b/docs/reference/preprocessing.md @@ -0,0 +1,3 @@ +:::preprocessing + options: + show_submodules: true \ No newline at end of file diff --git a/docs/reference/storage.md b/docs/reference/storage.md new file mode 100644 index 00000000..f77c9ee8 --- /dev/null +++ b/docs/reference/storage.md @@ -0,0 +1,3 @@ +:::storage + options: + show_submodules: true \ No newline at end of file diff --git a/docs/reference/terminal_tools.md b/docs/reference/terminal_tools.md new file mode 100644 index 00000000..2683e836 --- /dev/null +++ b/docs/reference/terminal_tools.md @@ -0,0 +1,5 @@ +# Terminal tools + +:::terminal_tools + options: + show_submodules: true \ No newline at end of file diff --git a/docs/reference/testing.md b/docs/reference/testing.md new file mode 100644 index 00000000..5bb1e308 --- /dev/null +++ b/docs/reference/testing.md @@ -0,0 +1,3 @@ +:::testing + options: + show_submodules: true \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..4476d53e --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,56 @@ +site_name: CIB Mango Tree +site_author: CIB Mango Tree +site_description: "An interactive python terminal UI wrapper for Mango Tree analyzers." +site_url: https://cibmangotree.org +repo_url: https://github.com/civictechdc/mango-tango-cli +copyright: Copyright © 2025 CIB Mango Tree +nav: + - "Home": + - "Overview": "index.md" + - "License": "license.md" + - "Contributing guide": "dev-guide.md" + - "Reference (CLI)": + - "Analyzer interface": "reference/analyzer_interface.md" + - "Components": "reference/components.md" + - "App": "reference/app.md" + - "Preprocessing": "reference/preprocessing.md" + - "Terminal tools": "reference/terminal_tools.md" + - "Importing": "reference/importing.md" + - "Meta": "reference/meta.md" + - "Testing": "reference/testing.md" + +theme: + name: material + logo: img/favicon.ico + features: + - navigation.tracking + - navigation.tabs + - navigation.path + - navigation.sections + - navigation.top + - navigation.tabs + - content.code.copy + - content.tooltips + - toc.follow + +plugins: + - mkdocstrings: + handlers: + python: + paths: [src] # search packages in the src folder + options: + show_root_heading: true + # show_category_heading: true + show_root_toc_entry: false + show_root_full_path: true + heading_level: 2 + docstring_style: google + parameter_headings: true + show_symbol_type_heading: True + show_symbol_type_toc: True + +markdown_extensions: + - toc: + baselevel: 2 + + - pymdownx.snippets \ No newline at end of file From 6a904302a7e5a013f029808ed37d535cfc34c737 Mon Sep 17 00:00:00 2001 From: Kristijan Armeni Date: Fri, 9 May 2025 11:59:50 -0400 Subject: [PATCH 02/18] add mkdostrings and deps to dev dependencies --- requirements-dev.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/requirements-dev.txt b/requirements-dev.txt index 0597a532..8bbae638 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -4,3 +4,9 @@ pyarrow-stubs==17.13 black==24.10.0 isort==5.13.2 pytest==8.3.4 + +mkdocs +mkdocstrings[python] +mkdocs-material +markdown +pymdown-extensions From c55a8459dfea90c5b0c62234b210c4d993a94539 Mon Sep 17 00:00:00 2001 From: Kristijan Armeni Date: Fri, 9 May 2025 14:26:01 -0400 Subject: [PATCH 03/18] update README.md, add bages and logo --- README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9fdb1451..e2f6b082 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,17 @@ -# mango-tango-cli: A python terminal wrapper for CIB Mango Tree analyzers +

mango-tango-cli

+

A Python command-line tool for detecting coordinated inauthentic behavior

+ +

+Mango logo +

+ +

+code +style: black +style: black +

+ +--- ## Requirements From 956c75b6caf585f2aa34e0e80f2bbeb8dd6129aa Mon Sep 17 00:00:00 2001 From: Kristijan Armeni Date: Wed, 14 May 2025 20:03:03 -0400 Subject: [PATCH 04/18] create guides folder --- docs/guides/contributing.md | 46 ++++++++++++++++++++++++++++++++ docs/{ => guides}/dev-guide.md | 48 ---------------------------------- mkdocs.yml | 4 ++- 3 files changed, 49 insertions(+), 49 deletions(-) create mode 100644 docs/guides/contributing.md rename docs/{ => guides}/dev-guide.md (89%) diff --git a/docs/guides/contributing.md b/docs/guides/contributing.md new file mode 100644 index 00000000..baf5bd50 --- /dev/null +++ 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/` or `bugfix/`. + - 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 b/docs/guides/dev-guide.md similarity index 89% rename from docs/dev-guide.md rename to docs/guides/dev-guide.md index 78e31821..8da7c6bb 100644 --- a/docs/dev-guide.md +++ b/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/` or `bugfix/`. - - 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/mkdocs.yml b/mkdocs.yml index 4476d53e..ab4f1395 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,7 +8,9 @@ nav: - "Home": - "Overview": "index.md" - "License": "license.md" - - "Contributing guide": "dev-guide.md" + - "Guides": + - "CLI design philosophy": "guides/dev-guide.md" + - "Development guide": "guides/contributing.md" - "Reference (CLI)": - "Analyzer interface": "reference/analyzer_interface.md" - "Components": "reference/components.md" From 57421e35dd6ba1486cbbb6ee12184a5cd197818f Mon Sep 17 00:00:00 2001 From: Kristijan Armeni Date: Thu, 15 May 2025 14:59:33 -0400 Subject: [PATCH 05/18] Add github workflow for docs build on pull request --- .github/workflows/docs.yml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..c808d6ee --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,23 @@ +# see: https://github.com/marketplace/actions/deploy-mkdocs +name: Publish docs via GitHub Pages + +on: pull_request + +jobs: + build: + name: Deploy docs + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v2 + + - 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-dev.txt \ No newline at end of file From c3fcbca4364bca66f3c42789f284f491b5911943 Mon Sep 17 00:00:00 2001 From: Kristijan Armeni Date: Mon, 19 May 2025 09:50:21 -0400 Subject: [PATCH 06/18] use a seperate, smaller requirements file for docs and use for workflow --- .github/workflows/docs.yml | 2 +- requirements-dev.txt | 6 ------ 2 files changed, 1 insertion(+), 7 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c808d6ee..d0b10695 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,4 +20,4 @@ jobs: CONFIG_FILE: mkdocs.yml EXTRA_PACKAGES: build-base # GITHUB_DOMAIN: github.myenterprise.com - REQUIREMENTS: requirements-dev.txt \ No newline at end of file + REQUIREMENTS: requirements-mkdocs.txt \ No newline at end of file diff --git a/requirements-dev.txt b/requirements-dev.txt index 8bbae638..0597a532 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -4,9 +4,3 @@ pyarrow-stubs==17.13 black==24.10.0 isort==5.13.2 pytest==8.3.4 - -mkdocs -mkdocstrings[python] -mkdocs-material -markdown -pymdown-extensions From b07a838f119173ef67f8b26bad8b639024513cf9 Mon Sep 17 00:00:00 2001 From: Kristijan Armeni Date: Mon, 19 May 2025 10:05:55 -0400 Subject: [PATCH 07/18] update readme esthetics a little bit --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index e2f6b082..f5170809 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -

mango-tango-cli

-

A Python command-line tool for detecting coordinated inauthentic behavior

+

mango-tango-cli

+

A Python command-line tool for detecting coordinated inauthentic behavior

-Mango logo +Mango logo

From 7ee6063d3c878da98153b6916dd9baa2c839f97d Mon Sep 17 00:00:00 2001 From: Kristijan Armeni Date: Mon, 19 May 2025 10:23:16 -0400 Subject: [PATCH 08/18] [fix] add requirements-mdocs.txt and remove cmake dependency --- requirements-mkdocs.txt | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 requirements-mkdocs.txt diff --git a/requirements-mkdocs.txt b/requirements-mkdocs.txt new file mode 100644 index 00000000..65b41f33 --- /dev/null +++ b/requirements-mkdocs.txt @@ -0,0 +1,5 @@ +mkdocs +mkdocstrings[python] +mkdocs-material +markdown +pymdown-extensions \ No newline at end of file From 0cda3f39422ab7fbec6975e2115ce8c37adb6332 Mon Sep 17 00:00:00 2001 From: Kristijan Armeni Date: Mon, 19 May 2025 10:23:34 -0400 Subject: [PATCH 09/18] fix links --- docs/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index 643748be..a8dc2afa 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,5 @@ # CIB Mango Tree Technical documentation -Welcome to the technical documentation website of 🥭 [CIB Mango Tree](www.cibmangotree.org) 🥭, a collaborative and open-source project to develop software that tests for coordinated inauthentic behavior (CIB) in datasets of online activity. +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 technical documentation, for a user-based perspective and project story see: [www.cibmangotree.org](www.cibmangotree.org) \ No newline at end of file +This is the technical documentation, for a user-based perspective and project story see: [www.cibmangotree.org](https://www.cibmangotree.org) \ No newline at end of file From 0ede5241146925a02aaf5c513c6746dff047142d Mon Sep 17 00:00:00 2001 From: VEDA95 Date: Tue, 17 Jun 2025 03:02:03 -0400 Subject: [PATCH 10/18] Wrote, "Getting Started" guide for technical docs. --- docs/guides/get-started.md | 105 +++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/guides/get-started.md diff --git a/docs/guides/get-started.md b/docs/guides/get-started.md new file mode 100644 index 00000000..e3dc3da4 --- /dev/null +++ b/docs/guides/get-started.md @@ -0,0 +1,105 @@ +# 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 +``` + +#### 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 +[Development Guide](./dev-guide.md) From c187e43fa9d43649a61ddd701b75df2680786186 Mon Sep 17 00:00:00 2001 From: VEDA95 Date: Tue, 17 Jun 2025 03:07:18 -0400 Subject: [PATCH 11/18] Added a link to the contributor workflow section under "Next Steps" in getting started section. --- docs/guides/get-started.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guides/get-started.md b/docs/guides/get-started.md index e3dc3da4..94a2c065 100644 --- a/docs/guides/get-started.md +++ b/docs/guides/get-started.md @@ -101,5 +101,4 @@ npm install --legacy-peer-deps # Next Steps -Once you have everything installed and running without any problems -[Development Guide](./dev-guide.md) +Once you have everything installed and running without any problems, the next step is to check out the [Contributor Workflow](./contributing.md) From 602158381d2a8815042994e97b7262d0f46933c5 Mon Sep 17 00:00:00 2001 From: Joe Karow <58997957+JoeKarow@users.noreply.github.com> Date: Tue, 24 Jun 2025 17:37:38 -0400 Subject: [PATCH 12/18] add scoped token permission --- .github/workflows/docs.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d0b10695..b7ecd625 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,14 +2,15 @@ name: Publish docs via GitHub Pages on: pull_request - +permissions: + pages: write jobs: build: name: Deploy docs runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v4 - name: Deploy docs uses: mhausenblas/mkdocs-deploy-gh-pages@master @@ -20,4 +21,4 @@ jobs: CONFIG_FILE: mkdocs.yml EXTRA_PACKAGES: build-base # GITHUB_DOMAIN: github.myenterprise.com - REQUIREMENTS: requirements-mkdocs.txt \ No newline at end of file + REQUIREMENTS: requirements-mkdocs.txt From d3ed25481a3043a5d5c7150212fdbdbdbd98f059 Mon Sep 17 00:00:00 2001 From: Joe Karow <58997957+JoeKarow@users.noreply.github.com> Date: Tue, 24 Jun 2025 17:52:22 -0400 Subject: [PATCH 13/18] use separate build / deploy actions --- .github/workflows/docs.yml | 35 +++++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b7ecd625..4c871087 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -3,7 +3,10 @@ name: Publish docs via GitHub Pages on: pull_request permissions: + contents: write + deployments: write pages: write + jobs: build: name: Deploy docs @@ -11,14 +14,26 @@ jobs: steps: - name: Checkout repository uses: actions/checkout@v4 + - name: Build + uses: Tiryoh/actions-mkdocs@v0.24.0 + with: + # mkdocs_version: 'latest' # option + #mkdocs_version: '1.1' # option + requirements: 'requirements-mkdocs.txt' # option + configfile: 'mkdocs.yml' # option + - name: Deploy + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./site - - 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 + # - 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 From f2f46fd9d5325bc761077d397a804a5f41b855b5 Mon Sep 17 00:00:00 2001 From: Joe Karow <58997957+JoeKarow@users.noreply.github.com> Date: Tue, 24 Jun 2025 17:54:38 -0400 Subject: [PATCH 14/18] use deploy key instead of github_token --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 4c871087..c9e6278c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -24,7 +24,7 @@ jobs: - name: Deploy uses: peaceiris/actions-gh-pages@v4 with: - github_token: ${{ secrets.GITHUB_TOKEN }} + deploy_key: ${{ secrets.GH_ACTIONS_DEPLOY_KEY }} publish_dir: ./site # - name: Deploy docs From 7719d331256f2aa76ca0b43a9a21e7afc9db8dc1 Mon Sep 17 00:00:00 2001 From: Joe Karow <58997957+JoeKarow@users.noreply.github.com> Date: Tue, 24 Jun 2025 18:12:10 -0400 Subject: [PATCH 15/18] use separate build & deploy actions. only deploy to prod from main -- others get a preview build --- .github/workflows/docs.yml | 30 +++++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c9e6278c..093a329b 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,7 +1,17 @@ # see: https://github.com/marketplace/actions/deploy-mkdocs name: Publish docs via GitHub Pages -on: pull_request +on: + pull_request: + types: + - opened + - reopened + - synchronize + - closed + push: + branches: + - main + permissions: contents: write deployments: write @@ -16,16 +26,26 @@ jobs: uses: actions/checkout@v4 - 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 - - name: Deploy - uses: peaceiris/actions-gh-pages@v4 + - uses: rossjrw/pr-preview-action@v1 + if: github.event_name == 'pull_request' + 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' with: - deploy_key: ${{ secrets.GH_ACTIONS_DEPLOY_KEY }} - publish_dir: ./site + folder: site/ + branch: gh-pages + clean-exclude: pr-preview + force: false # - name: Deploy docs # uses: mhausenblas/mkdocs-deploy-gh-pages@master From d1093a04aa54dd00e54ef112ab34b57b0a81eee6 Mon Sep 17 00:00:00 2001 From: Joe Karow <58997957+JoeKarow@users.noreply.github.com> Date: Tue, 24 Jun 2025 18:20:10 -0400 Subject: [PATCH 16/18] update workflow to use pull_request_target for better security and context --- .github/workflows/docs.yml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 093a329b..c51c0621 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,7 +2,7 @@ name: Publish docs via GitHub Pages on: - pull_request: + pull_request_target: types: - opened - reopened @@ -24,6 +24,9 @@ jobs: 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' @@ -33,7 +36,7 @@ jobs: requirements: 'requirements-mkdocs.txt' # option configfile: 'mkdocs.yml' # option - uses: rossjrw/pr-preview-action@v1 - if: github.event_name == 'pull_request' + if: github.event_name == 'pull_request_target' with: source-dir: site/ preview-branch: gh-pages From 5e1a204d3e22f8dcdce758100616db54f3da70aa Mon Sep 17 00:00:00 2001 From: Joe Karow <58997957+JoeKarow@users.noreply.github.com> Date: Tue, 24 Jun 2025 18:27:39 -0400 Subject: [PATCH 17/18] add manual trigger --- .github/workflows/docs.yml | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index c51c0621..b3db3589 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,6 +11,15 @@ on: push: branches: - main + workflow_dispatch: + inputs: + deploy_to: + description: 'Deployment destination' + type: choice + options: + - prod + - preview + permissions: contents: write @@ -36,14 +45,14 @@ jobs: requirements: 'requirements-mkdocs.txt' # option configfile: 'mkdocs.yml' # option - uses: rossjrw/pr-preview-action@v1 - if: github.event_name == 'pull_request_target' + if: github.event_name == 'pull_request_target' || (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' + if: (github.event_name == 'push' && github.ref_name == 'main') || (github.event_name == 'workflow_dispatch' && inputs.deploy_to == 'prod') with: folder: site/ branch: gh-pages From 5d8e963e696607c5f40d4459626c0d1c792bcb05 Mon Sep 17 00:00:00 2001 From: Joe Karow <58997957+JoeKarow@users.noreply.github.com> Date: Tue, 24 Jun 2025 18:29:22 -0400 Subject: [PATCH 18/18] change trigger back to pull_request --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b3db3589..1fe27f9f 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,7 +2,7 @@ name: Publish docs via GitHub Pages on: - pull_request_target: + pull_request: types: - opened - reopened @@ -45,7 +45,7 @@ jobs: requirements: 'requirements-mkdocs.txt' # option configfile: 'mkdocs.yml' # option - uses: rossjrw/pr-preview-action@v1 - if: github.event_name == 'pull_request_target' || (github.event_name == 'workflow_dispatch' && inputs.deploy_to == 'preview') + if: github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && inputs.deploy_to == 'preview') with: source-dir: site/ preview-branch: gh-pages