Guided tours

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,23 @@
+# Describe your changes:
+* 
+* 
+
+# This pull requests adresses/closes the following issues: 
+
+# Changes are staged [here]()
+(your GitHub Pages site or https://witty-bay-0dafe9a10.4.azurestaticapps.net/)
+
+# I have checked:
+(add x between the brackets to check the box; add checkboxes for checks relevant to your changes):
+* [ ] metadata search still works
+* [ ] opening pairwise viz from selection of two texts still works
+* [ ] opening pairwise viz from text reuse pane still works
+* [ ] opening diff from pairwise viz still works
+* [ ] opening one-to-many viz from metadata page still works
+* [ ] opening diff from one-to-many viz still works
+* [ ] ...
+
+# Reviewer: @...
+
+# Reviewer should check: 
+* [ ] ...

.github/workflows/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,23 @@
+# Describe your changes:
+* 
+* 
+
+# This pull requests adresses/closes the following issues: 
+
+# Changes are staged [here]()
+(your GitHub Pages site or https://witty-bay-0dafe9a10.4.azurestaticapps.net/)
+
+# I have checked:
+(add x between the brackets to check the box; add checkboxes for checks relevant to your changes):
+* [ ] metadata search still works
+* [ ] opening pairwise viz from selection of two texts still works
+* [ ] opening pairwise viz from text reuse pane still works
+* [ ] opening diff from pairwise viz still works
+* [ ] opening one-to-many viz from metadata page still works
+* [ ] opening diff from one-to-many viz still works
+* [ ] ...
+
+# Reviewer: @...
+
+# Reviewer should check: 
+* [ ] ...

.github/workflows/deploy-on-gh-pages-from-branch.yml

@@ -0,0 +1,35 @@
+name: Deploy to GitHub Pages from current branch
+
+on:
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout current branch
+        uses: actions/checkout@v3
+        with:
+          ref: ${{ github.ref_name }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build the app with dynamic PUBLIC_URL
+        run: PUBLIC_URL=/${{ github.event.repository.name }} npm run build
+
+      - name: Deploy to GitHub Pages
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          npm exec gh-pages -- \
+            -d build \
+            -r https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git

.github/workflows/deploy_from_branch.yml

@@ -0,0 +1,36 @@
+name: Deploy to GitHub Pages from chosen branch
+
+on:
+  workflow_dispatch:
+
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout current branch
+        uses: actions/checkout@v3
+        with: 
+          ref: ${{ github.ref_name }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 22.17.1  # or whatever version your project uses
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build the app
+        run: npm run build
+
+      - name: Deploy to GitHub Pages
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          npm exec gh-pages -- \
+            -d build \
+            -r https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git

README.md

@@ -1,94 +1,90 @@
 # KITAB explore 
 
-A web portal for the KITAB project.
+A web portal for the [KITAB project](https://kitab-project.org).
 
-The portal gives access to the OpenITI metadata and the KITAB text reuse data and visualisations.
+The portal gives access to the [OpenITI corpus](https://openiti.org/projects/OpenITI%20Corpus.html) metadata 
+and the [KITAB](https://kitab-project.org) text reuse data and visualisations.
 
-![Kitab Logo](public/logo192.png) 
+The website is live at https://kitab-project.org/explore
 
+![Kitab Logo](public/logo192.png) 
 
 ## Features
 
 - **Extensive Collection:** Browse through a vast repository of historical Arabic books from the OpenITI corpus.
 - **Metata Search Functionality:** Search for specific works by author, title and other metadata.
-- **Explore Text Reuse Data:** visualize the text reuse relations between two books, or between one book and all other books in the corpus
+- **Explore Text Reuse Data:** visualize the text reuse relations between two books, or between one book and all other books in the corpus.
 - **Download:** Download OpenITI text files and KITAB text reuse data.
 
-
-## Getting Started
-
-To get started with KITAB explore, follow these steps:
-
-1. **Clone the Repository:**
-
-   ```bash
-   git clone https://github.com/kitab-project-org/explore.git
-   ```
-
-2. **Install Dependencies:**
-
-   ```bash
-   cd kitabapps
-   npm install # Or use yarn if preferred
-   ```
-
-3. **Run the Application:**
-
-   ```bash
-   npm start
-   ```
-
-   4. **Access the Application:**
-
-   Open your web browser and navigate to http://localhost:8080.
-
-## Github Pages Build Process
-
-To build the file for gh-pages, follow these steps:
-
-1. **Install Github Pages:**
-
-   ```bash
-   npm install gh-pages
-   ```
-
-2. **Add Scripts Inside package.json File:**
-
-   "predeploy": "npm run build",
-   "deploy": "gh-pages -d build",
-
-3. **Build And Publish:**
-   try to build the app with
-
-   ```bash
-   npm run build
-   ```
-
-   then run this code:
-
-   ```bash
-   npm run deploy
-   ```
-
-4. **Live Link:**
-
-You will get the live link at this location - https://your-github-username.github.io/repo-name/
+## Branches:
+* **main** is the production branch, and served on GitHub pages (with alias https://kitab-project.org/explore)
+* **dev** is the main development branch, from which individual feature branches should be created
+* **uat** ("Unit Acceptance Testing") is the staging branch; whenever something is pushed to uat, 
+  a [GitHub Actions script](https://github.com/kitab-project-org/explore/blob/uat/.github/workflows/azure-static-web-apps-witty-bay-0dafe9a10.yml) 
+  builds the stable website and deploys to a test website on Azure (https://witty-bay-0dafe9a10.4.azurestaticapps.net/)
+
+## Git Workflow for contributors
+NB: we use a forking workflow so you can test the GitHub Pages deployment on your own GitHub Pages site
+
+The aim is to create small, short-lived feature branches, and have the main branch continuously updated.
+
+* pick or create an issue you want to work on (and assign it to yourself)
+* use [this GitHub Kanban board](https://github.com/orgs/kitab-project-org/projects/2/views/1?layout_template=board) so that others can keep track of who's working on what
+* (only the first time):
+  - Fork the repo https://github.com/kitab-project-org/explore/ on GitHub
+  - clone your fork to your local machine: `git clone https://github.com/<yourGithubUserName>/explore.git`
+  - create the connection to the original repo - call it "upstream": `git remote add upstream https://github.com/kitab-project-org/explore.git` 
+    if you run the command `git remote -v` now, it should show the remote branch in addition to "origin" - your fork
+* Create a feature branch based on the dev branch of the original repo:
+  ```
+  git fetch upstream
+  git checkout -b <branchName> upstream/dev
+  ```
+* (do development work, add and commit changes, test locally)
+* Push the changes to your fork: `git push origin <branchName>`
+* Stage a test instance of the app on your fork's GitHub pages or the Azure staging website (see below)
+* Create a pull request ([here](https://github.com/kitab-project-org/explore/compare)) from your feature branch on your fork 
+  to the dev branch on kitab-project-org (click "compare across forks" if your fork does not appear)
+  - include a link to your staged instance
+  - assign a reviewer
+* Reviewer thoroughly reviews the pull request and the staged website and communicates with the author about changes needed:
+  - test the new feature
+  - check whether the main functionality still works (this kind of check should be automated) - see the pull request template
+* Reviewer accepts the pull request
+* Reviewer pulls the changes to main
+* Reviewer deploys the main branch by running the GitHub Actions script (see below)
+* Delete your feature branch to keep the repo clean
+
+## Testing whether the app works: 
+* Locally (for testing the dynamic app): 
+  - In VSCode: run `npm ci` (only the first time), then `npm start` in the terminal; the website should now be served on http://localhost:8080
+* On your own branch's GitHub Pages (for testing the static website):
+  - NB: this only works if your GitHub username is whitelisted in the API repo (Masoumeh's, Mathew's, Peter's and Sohail's GitHub usernames are all whitelisted)
+  - In the fork on your GitHub page, go to Actions, and choose "Deploy to Github Pages from current branch" in the left-hand column
+  - Then, click the "Run workflow" button, choose the name of your feature branch, and click the green "Run workflow" button
+  - (only the first time: go to the Settings of your GitHub pages fork, choose "Pages", and in the "Branch" section under "Build and deployment", set the branch to "gh-pages" and the folder to "/ (root)".)
+  - The website should now be deployed to https://\<yourGithubUserName\>.github.io/explore
+* On an azure server:
+  - Pull the changes into the **uat** branch; this will automatically build the static pages and deploy them to an azure page: https://witty-bay-0dafe9a10.4.azurestaticapps.net/
+
+## Deploying the app to https://kitab-project.org/explore :
+* Test the deployment as described above
+* Pull changes to the main branch
+* In the kitab-project-org GitHub page, go to [Actions](https://github.com/kitab-project-org/explore/actions), and choose "Deploy to Github Pages from current branch" in the left-hand column
+* Click the "Run workflow" button, select the "main" branch from the dropdown, and click the green "Run workflow" button
+
+## Description of the component structure
+See [this document](https://docs.google.com/presentation/d/1OeujYqQMVfyVTf5daPZLQdqFnynhK84I_kjeUzXL9Bs/edit?usp=sharing)
 
 ## Contributing
 
-We welcome contributions to enhance the library and improve its features. To contribute:
-
-    Fork the repository.
-    Create a new branch for your feature: git checkout -b feature-name.
-    Commit your changes: git commit -m 'Add some feature'.
-    Push to the branch: git push origin feature-name.
-    Submit a pull request.
+We welcome contributions to enhance the library and improve its features. If you would like to contribute, contact the KITAB team.
 
 ## Issues
 
 If you encounter any issues or have suggestions, please open an issue. We appreciate your feedback!
 License - https://github.com/kitab-project-org/explore/issues/new
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT License.
 
 ## End

build/_redirects

@@ -0,0 +1 @@
+/*      /index.html     200

build/asset-manifest.json

@@ -0,0 +1,18 @@
+{
+  "files": {
+    "main.css": "./static/css/main.e027b100.css",
+    "main.js": "./static/js/main.a8edc8da.js",
+    "static/media/GentiumPlus-Regular.ttf": "./static/media/GentiumPlus-Regular.945cd08c203a847922c4.ttf",
+    "static/media/pairwise-screenshot.png": "./static/media/pairwise-screenshot.8c856de79a8c677c86ea.png",
+    "static/media/one-to-all-screenshot.png": "./static/media/one-to-all-screenshot.795e4b8e85a722d4c85e.png",
+    "static/media/ismc.jpg": "./static/media/ismc.97d3e6bb1d5a69021aa6.jpg",
+    "static/media/flag.jpg": "./static/media/flag.e85b5883a003971205df.jpg",
+    "index.html": "./index.html",
+    "main.e027b100.css.map": "./static/css/main.e027b100.css.map",
+    "main.a8edc8da.js.map": "./static/js/main.a8edc8da.js.map"
+  },
+  "entrypoints": [
+    "static/css/main.e027b100.css",
+    "static/js/main.a8edc8da.js"
+  ]
+}

build/index.html

@@ -0,0 +1 @@
+<!doctype html><html lang="en"><head><meta charset="utf-8"/><link rel="icon" href="./favicon.ico"/><meta name="viewport" content="width=device-width,initial-scale=1"/><meta name="theme-color" content="#000000"/><meta name="description" content="Web site created using create-react-app"/><link rel="apple-touch-icon" href="./logo192.png"/><link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Amiri&display=swap"/><link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons"/><link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons"/><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.0/css/all.min.css"/><meta name="viewport" content="initial-scale=1,width=device-width"/><link rel="manifest" href="./manifest.json"/><link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/cookieconsent@3/build/cookieconsent.min.css"/><script src="https://cdn.jsdelivr.net/npm/cookieconsent@3/build/cookieconsent.min.js" data-cfasync="false"></script><script async src="https://www.googletagmanager.com/gtag/js?id=UA-184803711-1"></script><title>KITAB Explore</title><script defer="defer" src="./static/js/main.a8edc8da.js"></script><link href="./static/css/main.e027b100.css" rel="stylesheet"></head><body><noscript>You need to enable JavaScript to run this app.</noscript><div id="root"></div></body></html>

build/manifest.json

@@ -0,0 +1,25 @@
+{
+  "short_name": "KITAB App",
+  "name": "KITAB Application",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "64x64 32x32 24x24 16x16",
+      "type": "image/x-icon"
+    },
+    {
+      "src": "logo192.png",
+      "type": "image/png",
+      "sizes": "192x192"
+    },
+    {
+      "src": "logo512.png",
+      "type": "image/png",
+      "sizes": "512x512"
+    }
+  ],
+  "start_url": ".",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}

build/robots.txt

@@ -0,0 +1,14 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow: /
+
+# Please don't scrape the OpenITI or KITAB data using this website.
+# All data is available in easily downloadable format on GitHub and Zenodo: 
+# * OpenITI corpus metadata: https://github.com/OpenITI/kitab-metadata-automation/tree/master/releases
+# * OpenITI corpus texts: 
+#   - primary versions only (best solution for most): https://doi.org/10.5281/zenodo.7764025
+#   - all versions: https://doi.org/10.5281/zenodo.10021513
+# * KITAB text reuse data:
+#   - pairwise csv files: https://doi.org/10.5281/zenodo.4362368
+#   - one-to-all csv files: https://github.com/kitab-project-org/one_to_all
+# For more info on the data, check https://kitab-project.org/corpus-and-data