From d81f2bf0e16206a3098369f1f394220f7ede9b02 Mon Sep 17 00:00:00 2001 From: ggbaro <46573388+ggbaro@users.noreply.github.com> Date: Mon, 25 Dec 2023 11:18:09 +0100 Subject: [PATCH] fixed docs --- .../swapanything/backend/airtable.md | 3 + .../swapanything/backend/simple.md | 3 + docs/api-reference/swapanything/index.md | 3 + docs/api-reference/swapanything/select.md | 3 + docs/getting-started.md | 127 ++++++++++++++++++ docs/getting-started/index.md | 1 - docs/how-to/index.md | 1 - docs/index.md | 20 ++- docs/user-guide/index.md | 1 - mkdocs.yml | 12 ++ 10 files changed, 168 insertions(+), 6 deletions(-) create mode 100644 docs/api-reference/swapanything/backend/airtable.md create mode 100644 docs/api-reference/swapanything/backend/simple.md create mode 100644 docs/api-reference/swapanything/index.md create mode 100644 docs/api-reference/swapanything/select.md create mode 100644 docs/getting-started.md delete mode 100644 docs/getting-started/index.md delete mode 100644 docs/how-to/index.md delete mode 100644 docs/user-guide/index.md diff --git a/docs/api-reference/swapanything/backend/airtable.md b/docs/api-reference/swapanything/backend/airtable.md new file mode 100644 index 0000000..6aa50ae --- /dev/null +++ b/docs/api-reference/swapanything/backend/airtable.md @@ -0,0 +1,3 @@ +# airtable + +::: swapanything.backend.airtable diff --git a/docs/api-reference/swapanything/backend/simple.md b/docs/api-reference/swapanything/backend/simple.md new file mode 100644 index 0000000..2367feb --- /dev/null +++ b/docs/api-reference/swapanything/backend/simple.md @@ -0,0 +1,3 @@ +# simple + +::: swapanything.backend.simple diff --git a/docs/api-reference/swapanything/index.md b/docs/api-reference/swapanything/index.md new file mode 100644 index 0000000..b564453 --- /dev/null +++ b/docs/api-reference/swapanything/index.md @@ -0,0 +1,3 @@ +# swapanything + +::: swapanything diff --git a/docs/api-reference/swapanything/select.md b/docs/api-reference/swapanything/select.md new file mode 100644 index 0000000..fa8acfb --- /dev/null +++ b/docs/api-reference/swapanything/select.md @@ -0,0 +1,3 @@ +# airtable + +::: swapanything.select diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..5037e99 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,127 @@ +# Getting Started + + +### Your first matching round + +This library allow you to match subjects (people, things, whatever) depending +on their availability slots (calendar slots, timeframe, location, +any combination of the abovementioned). Truly, you can use this library as +backend for any sort of matching need. + +The simplest way to test this library is to use the `swapanything` python +package to make a simple swapping exercise. + +```python +from swapanything.backend import simple as backend +from swapanything.select import select_matches +import pandas as pd + +availabilities = [ + ["KungFury", "9:00"], + ["KungFury", "10:00"], + ["KungFury", "13:00"], + ["KungFury", "14:00"], + ["Triceracop", "9:00"], + ["Triceracop", "11:00"], + ["Hackerman", "10:00"], + ["Hackerman", "11:00"], + ["Katana", "12:00"], + ["Barbarianna", "12:00"], + ["Thor", "13:00"], + ["Thor", "14:00"], + ["Thor", "15:00"], + ["T-Rex", "15:00"], + ["T-Rex", "16:00"], + ["Hoff 9000", "16:00"], +] + +availabilities_df = pd.DataFrame( + availabilities, columns=["subject", "availability"] +) + +be = backend.SimpleBackend( + availabilities=availabilities_df, + availabilities_column="availability", + availability_subject_column="subject", +) + +all_possible_matches = be.get_all_matches() +# subject availability +# 0 (Barbarianna, Katana) (12:00,) +# 1 (Hackerman, KungFury) (10:00,) +# 2 (Hackerman, Triceracop) (11:00,) +# 3 (Hoff 9000, T-Rex) (16:00,) +# 4 (KungFury, Thor) (13:00, 14:00) +# 5 (KungFury, Triceracop) (9:00,) +# 6 (T-Rex, Thor) (15:00,) + +select_matches(all_possible_matches, backend=be) +# subject availability +# 0 (Barbarianna, Katana) (12:00,) +# 1 (Hackerman, Triceracop) (11:00,) +# 2 (Hoff 9000, T-Rex) (16:00,) +# 3 (KungFury, Thor) (13:00, 14:00) + +``` + +Imagine now that we want to provide a super high importance +to the match `(KungFury, Triceracop)`. +With `select_matches` you can use match scores, and the +algorithm will try to maximize number of matches and total +score! + +This way we ensure that high quality matches are selected. + +```python +scores = [1, 1, 1, 1, 1, 9001, 1] +# (KungFury, Triceracop)... it's over 9000! +select_matches(all_possible_matches, backend=be, match_scores=scores) +# subject availability +# 0 (Barbarianna, Katana) (12:00,) +# 1 (KungFury, Triceracop) (9:00,) +# 2 (T-Rex, Thor) (15:00,) + +``` + +### Advanced Backends + +With python, it is possible to integrate `swapanything` in your application +or custom tool. `swapanything` comes with some pre-configured data backends +(e.g. Airtable, Excel Spreadsheets, SQL) that you can easily use to +kickstart your swaping-based app! + +#### Airtable + +Install airtable dependencies: + +```shell +pip install swap-anything[airtable] +``` + +```python +from swapanything.backend import airtable +from swapanything.select import select_matches +import os + + +airtable_backend = airtable.AirTableBackend( + # subject_id is the record id of the subjects table + subject_features=["Interests", "Tags", "Score1", "Score2"], + availability_subject_column="AvailabilitiesSubjectId", + availabilities_column="Availabilities", + exclusions_subject_columns=["Subject1", "Subject2"] + # Tables + subjects_table_name="Subjects", + availabilities_table_name="Availabilities", + exclusions_table_name="Matches", + # Airtable credentials + client_id=os.environ["AIRTABLE_BASE_ID"], + client_secret=os.environ["AIRTABLE_API_KEY"], +) + +subjects = airtable_backend.get_subjects() +availabilities = airtable_backend.get_availabilities() + +all_matches = be.get_all_matches(exclusions=True) +selected = select_matches(matches, backend=airtable_backend) +``` diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md deleted file mode 100644 index bad5562..0000000 --- a/docs/getting-started/index.md +++ /dev/null @@ -1 +0,0 @@ -# Getting Started diff --git a/docs/how-to/index.md b/docs/how-to/index.md deleted file mode 100644 index 56d3f55..0000000 --- a/docs/how-to/index.md +++ /dev/null @@ -1 +0,0 @@ -# How-to... diff --git a/docs/index.md b/docs/index.md index 67e2c1f..f0aa4c9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,7 +6,21 @@ hide: # Swap Anything Docs -
+
swap-anything-logo -

Welcome to Swap Anything!

-

+
+# Welcome to Swap Anything! + +A mix and match (swap) library to empower swapping-based projects. + +[![Docs](https://github.com/founderswap/swap-anything/actions/workflows/build_docs.yaml/badge.svg)](https://founderswap.github.io/swap-anything/) +[![Tests](https://github.com/founderswap/swap-anything/actions/workflows/test.yaml/badge.svg)](https://github.com/founderswap/swap-anything/actions/workflows/test.yaml) +[![codecov](https://codecov.io/gh/founderswap/swap-anything/graph/badge.svg?token=QF6L5Y8EPM)](https://codecov.io/gh/founderswap/swap-anything) +[![PyPI version](https://badge.fury.io/py/swap-anything.svg)](https://badge.fury.io/py/swap-anything) + +NOTE: `swapanything` is still in its early steps. If you want to +contribute or sponsor this project, visit +[www.founderswap.xyz](https://www.founderswap.xyz) + +
+
diff --git a/docs/user-guide/index.md b/docs/user-guide/index.md deleted file mode 100644 index cd3d452..0000000 --- a/docs/user-guide/index.md +++ /dev/null @@ -1 +0,0 @@ -# User Guide diff --git a/mkdocs.yml b/mkdocs.yml index 1e0421a..e352abd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,6 +50,7 @@ plugins: markdown_extensions: - def_list + - md_in_html - pymdownx.superfences: custom_fences: - name: mermaid @@ -68,3 +69,14 @@ markdown_extensions: # embed code - pymdownx.snippets + +nav: +- Swap Anything: index.md +- Getting Started: getting-started.md +- Api Reference: + - swapanything: + - api-reference/swapanything/index.md + - backend: + - api-reference/swapanything/backend/simple.md + - api-reference/swapanything/backend/airtable.md + - select: api-reference/swapanything/select.md