Merge pull request #1 from wapuugotchi/add-docs

Consolidate docs here

.github/workflows/pages.yml

@@ -0,0 +1,49 @@
+name: build and publish docs with Jekyll
+
+on:
+  push:
+    branches:
+      - main
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+    contents: read
+    pages: write
+    id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+    group: "pages"
+    cancel-in-progress: false  
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container:
+      image: ruby:3.3
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install dependencies
+      run: bundle install
+    - name: Build docs
+      run: bundle exec jekyll build
+      env:
+        JEKYLL_ENV: production
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
+

.gitignore

@@ -0,0 +1,3 @@
+_site/
+.jekyll-cache/
+.DS_Store

Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem "jekyll"
+gem "just-the-docs"

Gemfile.lock

@@ -0,0 +1,81 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.6)
+      public_suffix (>= 2.0.2, < 6.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.2.3)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.16.3)
+    forwardable-extended (2.6.0)
+    google-protobuf (3.25.3-aarch64-linux)
+    http_parser.rb (0.8.0)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.3.3)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    just-the-docs (0.8.0)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (5.0.4)
+    rake (13.1.0)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.6)
+    rouge (4.2.0)
+    safe_yaml (1.0.5)
+    sass-embedded (1.71.1-aarch64-linux-gnu)
+      google-protobuf (~> 3.25)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.5.0)
+    webrick (1.8.1)
+
+PLATFORMS
+  aarch64-linux-gnu
+
+DEPENDENCIES
+  jekyll
+  just-the-docs
+
+BUNDLED WITH
+   2.5.3

README.md

@@ -0,0 +1,8 @@
+# Wapuugotchi Documentation
+This repository contains the documentation for the whole project.
+
+## Build
+It gets automatically built over GitHub actions after merging the contents into the main repository and deployed to https://doc.wapuugotchi.com.
+
+## Build locally
+To build the documentation locally, you need docker as prerequisite. Then start the service by using `docker-compose up -d`. You can stop it with `docker-compose down`.

_config.yml

@@ -0,0 +1,2 @@
+theme: just-the-docs
+source: ./docs

docker-compose.yml

@@ -0,0 +1,10 @@
+version: '3'
+services:
+  jekyll:
+    image: ruby:3.3
+    ports:
+      - "4000:4000"
+    volumes:
+      - .:/opt/docs
+    working_dir: /opt/docs
+    command: sh -c "bundle install && bundle exec jekyll serve --config _config.yml --host '0.0.0.0'"

docs/collection/index.md

@@ -0,0 +1,79 @@
+---
+layout: default
+title: WappuuGotchi Collection
+---
+# WappuuGotchi Collection
+
+This API provides the wapuu collection for the wapuugotchi plugin. They can be found [here](https://api.wapuugotchi.com/collection/).
+The schema can be found [here](https://api.wapuugotchi.com/schema/collection/).
+
+## Element structure
+
+The different parts are structured in folders e.g. the balls are placed under `/_balls`.
+Each element is placed in its own folder and needs a `image.svg`, `preview.png` and a `meta.md` file.
+
+The folder name needs to be written in **snake case**.
+
+The `meta.md` is written like this:
+```md
+---
+slug: classic
+name: Classic
+key: b5fb043f-76c6-41aa-9f3a-47bc445f52b7 (randomly generated)
+---
+```
+
+Other optional values are:
+
+* author: the author of the element
+* description: the description for the element
+* published: the publishing date of the element
+* licsense: the license of the element
+* price: the needed coins for unlocking the element (default: 0)
+
+Scanned folders are:
+
+* `_balls` for ball elements
+* `_coats` for coat elements
+* `_caps` for cap elements
+* `_fur` for fur elements
+* `_items` for item elements
+* `_shoes` for shoe elemeps
+
+## Adding new items
+
+To add a new element, just create a new folder in the corresponding folder and add the needed files.
+After that, create a pull request and wait for it to be merged.
+
+The svg needs to follow this structure:
+
+```html
+<svg id="wapuugotchi_svg__wapuu" width="200" version="1.1" viewBox="0 0 1e3 1e3" xmlns="http://www.w3.org/2000/svg">
+	<g id="RightArm--group">
+	</g>
+	<g id="Tail--group">
+	</g>
+	<g id="Body--group">
+	</g>
+	<g id="RightHand--group">
+	</g>
+	<g id="RightFoot--group">
+	</g>
+	<g id="RightEar--group">
+	</g>
+	<g id="Head--group">
+	</g>
+	<g id="LeftEar--group">
+	</g>
+	<g id="Face--group">
+	</g>
+	<g id="LeftLeg--group">
+	</g>
+	<g id="LeftFoot--group">
+	</g>
+	<g id="LeftArm--group">
+	</g>
+</svg>
+```
+
+Groups which are not needed can be removed but groups which have to be on a specific layer need to be kept even without content.

docs/user-handbook/index.md

@@ -0,0 +1,61 @@
+---
+layout: default
+title: WapuuGotchi User Handbook
+permalink: index.html
+nav_order: 1
+---
+# WapuuGotchi User Handbook
+Welcome to Wapuugotchi, a groundbreaking project that brings a whole new level of personalization, fun, and rewards to your everyday life! At its core, Wapuugotchi combines the charm of Wapuu characters with the excitement of gamified notifications and unlockable rewards, creating an unparalleled experience like no other.
+
+Say goodbye to mundane notifications and hello to Wapuugotchi's delightful and personalized Wapuu characters. These adorable digital companions will accompany you throughout your day, reflecting your unique personality and preferences. With a vast array of customization options, you can design your Wapuu to be as individual as you are, making every interaction a joyful and personalized experience.
+
+But Wapuugotchi is more than just cute characters; it's an engaging and entertaining journey. The gamified notifications turn daily tasks and activities into interactive challenges, making even the most routine activities a delightful experience. As you complete tasks and conquer challenges, you'll earn points and unlock exciting rewards, adding a touch of excitement to every accomplishment.
+
+Moreover, the world of Wapuugotchi is brimming with unlockable surprises and customization options. As you progress, you'll discover a treasure trove of rewards, from special costumes and accessories for your Wapuu to exclusive themes and backgrounds, allowing you to create a truly unique and captivating digital companion.
+
+Get ready to embark on an unforgettable adventure with Wapuugotchi, where your daily routines transform into exciting quests and where personalized Wapuu characters brighten your every moment. Join us in this one-of-a-kind project that promises to revolutionize the way you engage with technology and bring a smile to your face every step of the way. Welcome to Wapuugotchi, your personalized world of joy, fun, and endless possibilities.
+
+## Install plugin
+The installation of the plugin is very straightforward. You can download it from the WordPress.org Plugin Directory as zip file or you can install it directly from your WordPress over the default plugin area. For that, you click on *Plugins* in the sidebar navigation and then on *Add New*. You will find Wapuugotchi over the search.
+
+## Dashboard
+After the installation, you will see your Wapuu in the Dashboard area on the bottom right corner. Your new friend will show you notifications here.
+
+![Wapuu in the dashboard](./assets/wapuugotchi_on_dashboard.png)
+
+## Sidebar navigation
+You wil find *WapuuGotchi* in the sidebar navigation menu of WordPress. When you click on it, you will be redirected to the *Customizer* by default. There is another page you can access, the *Quest Log*. 
+
+![Sidebar navigation options](./assets/sidebar_navigation.png)
+
+## Configure your Wapuu
+To configure your little pal, the plugin provides you with a boutique full of items which you already own or which can be exchanged for precious pearls. To enter the boutique click on *WapuuGotchi* in the sidebar navigation. You should see the customizer now.
+
+![Wapuu Customizer](./assets/customizer.png)
+
+Here in the customizer, you have different types of wearables, which you can use to dress your Wapuu. First of all you have some basic shapes, which differ in form and color. There is a section with things which the Wapuu can hold, like orbs or guitars. Furthermore you can give your little fellow a hat, a haircut or even a crown. Then you have a category with general accessiores like a superhero cape, a baguette or smart-looking glasses. Your Wapuu can also wear a sweater or a t-shirt. And finally you can also dress him with different shoes, which suit to the rest of their outfit.
+
+Some of the items are locked in the beginning and can be unlocked through pearls.
+
+![A locked item in the Customizer](./assets/customizer_locked_item.png)
+
+When you click on a locked wearable, a modal will popup and ask you if you want to buy this item. On the top right you can find an information icon. When you hover over that item, you will see more information about the currently shown Wapuu. If you click on *OK*, you confirm your purchase and therefore unlock the item.
+
+A green bar in the customizer shows you how much pearls currently are in your possession.
+
+![Pearls balance bar in Wapuu customizer](./assets/pearls_balance.png)
+
+You can also name your little fellow. Above your Wapuu you can see a text field. Just change the standard Wapuu's name *Wapuu* into something you like more.
+
+### Multiple wearables from one category
+Sometimes you have the possibility to use multiple items from a category. This is possible for example with the category which provides accessoires all around the head like hats or fancy haircuts. The order in which you select the items will be used to determine in which order the items should be rendered. The rule is: the first item you select, it the one which is the farthest in the background. It is like you would stack items on top of each other. So if you select a hat and then a haircut, you will end up having the hairs rendered in the foreground.
+
+![Wapuu with weird looking hair in front of wizard hat](./assets/hairs_in_front_of_wizard_hat.png)
+
+## Pearls
+In the whimsical universe of Wapuugotchi, pearls have emerged as the cherished currency, opening a gateway to a treasure trove of delightful wearables for your beloved Wapuu companions. Through daring quests and exciting challenges, users have the opportunity to earn these precious pearls, embarking on thrilling adventures that test their wit, courage, and creativity. With each successfully completed quest, gleaming pearls are added to their collection, bringing them one step closer to adorning their digital companions with a dazzling array of costumes, accessories, and enchanting customizations. The pursuit of pearls adds an element of excitement and accomplishment to Wapuugotchi, empowering users to infuse their Wapuus with a unique charm that reflects their own personality and style. So, dive into the world of quests, earn your pearls, and let your imagination soar as you create a kaleidoscope of wonders for your cherished Wapuugotchi companions.
+
+### Earning pearls
+You can do quests to earn pearls. To see which quests are available, click on *WapuuGotchi* in the sidebar menu and then on *Quest Log*. You see two areas. The first tells you which quests are available, how to solve them, and how many pearls you will receive for finishing that quest. The second area shows you the list of resolved quests.
+
+![Pearls balance bar in Wapuu customizer](./assets/active_quests.png)