Merge pull request #3 from sensein/docs

kabilar · web-flow · commit 90e3a822c360 · 2025-02-24T16:20:49.000-06:00
Updated Documentation + Github Action
diff --git a/.github/workflows/build_deploy.yml b/.github/workflows/build_deploy.yml
@@ -22,7 +22,7 @@ jobs:
       pages: write
       id-token: write
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
 
     # Install dependencies
     - name: Set up Python 3.11
@@ -31,15 +31,15 @@ jobs:
         python-version: 3.11
 
     - name: Install dependencies
-      run: |
-        pip install -r docs/requirements.txt
+      run: | 
+        pip install -r docs/requirements.txt   
 
     # (optional) Cache your executed notebooks between runs
     # if you have config:
     # execute:
     #   execute_notebooks: cache
     - name: cache executed notebooks
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: docs/_build/.jupyter_cache
         key: jupyter-book-cache-${{ hashFiles('requirements.txt') }}
@@ -51,11 +51,11 @@ jobs:
 
     # Upload the book's HTML as an artifact
     - name: Upload artifact
-      uses: actions/upload-pages-artifact@v2
+      uses: actions/upload-pages-artifact@v3.0.1
       with:
         path: "docs/_build/html"
 
     # Deploy the book's HTML to GitHub Pages
     - name: Deploy to GitHub Pages
       id: deployment
-      uses: actions/deploy-pages@v2
+      uses: actions/deploy-pages@v4
diff --git a/.github/workflows/codespell.yml b/.github/workflows/codespell.yml
@@ -0,0 +1,29 @@
+# Codespell configuration is within .codespellrc
+---
+name: Codespell
+
+on:
+  push:
+    branches: [main, docs]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  codespell:
+    name: Check for spelling errors
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Annotate locations with typos
+        uses: codespell-project/codespell-problem-matcher@v1
+
+      - name: Run Codespell
+        uses: codespell-project/actions-codespell@v2
+        with:
+          skip: '*.pyc,*.git,*.svg,references.bib' 
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,14 @@
+FROM python:3.10-slim
+
+# The container will always run in /docs
+WORKDIR /docs
+
+# We won't COPY here, because we rely on the volume mount for local dev.
+
+# Install dependencies
+RUN pip install --no-cache-dir -r docs/requirements.txt
+
+EXPOSE 8040
+
+# Start a live server that rebuilds on changes
+CMD ["sphinx-autobuild", ".", "_build/html", "--port", "8040", "--host", "0.0.0.0"]
diff --git a/README.md b/README.md
@@ -5,8 +5,7 @@ This repository contains the Jupyter Book documentation for BrainKB.
 ## Requirements
 
 ```
-pip install -U jupyter-book sphinx-autobuild
-
+pip install -r docs/requirements.txt
 ```
 
 ## Running
@@ -30,5 +29,7 @@ Build and watch the Jupyter Book on port other than 8000, i.e., the default one.
 sphinx-autobuild . _build/html --open-browser --port 8009  
 ```
 
-**Note:** You need to be inside the jupyterbook directory and run the command, otherwise, replace **"."** with appropriate path.
+**Note:** 
+- If the Mermaid extension does not automatically add `sphinxcontrib.mermaid` to the generated `conf.py`, you will need to manually include it in the `extensions` list to enable rendering of Mermaid diagrams.
+- You need to be inside the jupyterbook directory and run the command, otherwise, replace **"."** with appropriate path.
 
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -0,0 +1,16 @@
+version: '3.8'
+
+services:
+  brainkb-jupyterbook:
+    build: .
+    ports:
+      - "8040:8040"
+    volumes:
+      - ./docs:/docs
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8040"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -3,22 +3,30 @@
 
 title: BrainKB
 author: Tek Raj Chhetri (tekraj@mit.edu)
-logo: logo.png
+logo: images/logo.png
 
-# Force re-execution of notebooks on each build.
+# Force re-execution of notebooks on each build
 # See https://jupyterbook.org/content/execute.html
 execute:
   execute_notebooks: force
 
-# Define the name of the latex output file for PDF builds
+# Define the name of the LaTeX output file for PDF builds 
 latex:
   latex_documents:
     targetname: book.tex
 
-# Add a bibtex file so that we can create citations
+# Add a BibTeX file so that we can create citations
 bibtex_bibfiles:
   - references.bib
 
+# Enable Mermaid in JupyterBook
+#https://opencomputinglab.github.io/SubjectMatterNotebooks/diagram/sphinx-diagrammers.html
+sphinx:
+  extra_extensions:
+    - sphinxcontrib.mermaid
+  config:
+    bibtex_reference_style: author_year
+
 # Information about where the book exists on the web
 repository:
   url: https://github.com/sensein/brainkbdocs  # Online location of your book
@@ -30,7 +38,3 @@ repository:
 html:
   use_issues_button: true
   use_repository_button: true
-
-sphinx:
-  config:
-    bibtex_reference_style: author_year 
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -31,9 +31,11 @@ parts:
     numbered: True 
     chapters:
     - file: benchmark 
-  - caption: Miscellaneous
+  - caption: Research Outputs and Software Tools
     numbered: True 
     chapters:
     - file: list_of_libaries
+    - file: publications
+
   
  
diff --git a/docs/brainkbui.md b/docs/brainkbui.md
@@ -1,5 +1,61 @@
-# User Interface Overview
-The currently deployment can be accessed at [http://3.149.235.227:3000/](http://3.149.235.227:3000/).
+# User Interface Overview 
+
+## Overview
+
+The BrainKB UI (user interface), accessible at [beta.brainkb.org](https://beta.brainkb.org), is a user-centric interface designed to interact with the BrainKB knowledge graph infrastructure. It enables neuroscientists, researchers, and practitioners to explore, search, analyze, and visualize neuroscience knowledge effectively. The platform integrates a range of tools and features that facilitate evidence-based decision-making, making it an essential resource for advancing neuroscience research.
+ 
+**Key Features:**
+- **Search**: Allows users to filter and refine queries based on criteria like species, data type, and file size.
+- **Interactive Visualizations**: Offers dynamic visual representations of knowledge graphs to enhance understanding and exploration.
+- **Collaboration Support**: Facilitates shared exploration and collaboration, such as contributing assertions and evidence.
+
+This beta release, currently in the development stage, highlights the evolving capabilities (also note that all features are not yet available) of BrainKB and actively invites user feedback to further enhance its functionality and usability.
+
+## Rapid Release
+The sequence diagram below illustrates the steps involved in the rapid release process. Currently, the workflow is semi-automated, particularly in the stages of fetching data from the graph database (Oxigraph) and uploading it to an AWS S3 bucket.
+The data from AWS S3 is automatically retrieved, processed, and displayed in the UI, allowing users to download it seamlessly. {numref}`brainkb_data_release` presents the visualization of the data retrieved from the AWS S3 bucket and displayed in the UI.
+
+Data in AWS is organized hierarchically by release, adhering to a structured directory pattern that must be followed when uploading data ({numref}`brainkb_data_release_aws_s3_directory_structure`). {numref}`brainkb_data_release_aws_s3_ui_mapping` demonstrates how this AWS directory structure is mapped to the user interface.
+
+```{mermaid} 
+sequenceDiagram
+    actor User
+    participant UI as User Interface
+    participant DB as Graph Database
+    participant S3 as AWS S3 Bucket
+
+    rect rgba(230, 210, 231, 0.5)
+    note right of User: Manual Steps
+    User ->> DB: Fetch Data from Graph Database
+    DB -->> User: Data Retrieved
+    User ->> S3: Upload Data to S3
+    S3 -->> User: Confirm Upload
+    end
+
+    rect rgba(200, 255, 200, 0.5)
+    note right of UI: Automated Steps
+    UI ->> S3: Fetch Data from S3
+    S3 -->> UI: Data Retrieved
+    UI ->> UI: Process and Visualize Data
+    UI ->> User: Display Data for Download
+    end
+```
+
+```{figure} images/data-release.png
+:name: brainkb_data_release
+BrainKB rapid release page.
+```
+
+
+```{figure} images/brainkb_rapid_release.png
+:name: brainkb_data_release_aws_s3_directory_structure
+BrainKB rapid release: Organized AWS S3 bucket directory structure for efficient data management.
+```
+```{figure} images/data_release_aws_s3_ui_mapping.png
+:name: brainkb_data_release_aws_s3_ui_mapping
+Mapping BrainKB's AWS S3 bucket directory structure to the user interface for streamlined data access and visualization.
+```
+## Snapshots of UI
 
 ```{figure} images/home.png
 :name: brainkb_uihome_figure
@@ -9,4 +65,5 @@ BrainKB UI home page.
 ```{figure} images/login.png
 :name: brainkb_uilogin_figure
 BrainKB UI login page.
-```
+```
+
diff --git a/docs/conf.py b/docs/conf.py
@@ -9,7 +9,7 @@
 comments_config = {'hypothesis': False, 'utterances': False}
 copyright = '2023'
 exclude_patterns = ['**.ipynb_checkpoints', '.DS_Store', 'Thumbs.db', '_build']
-extensions = ['sphinx_togglebutton', 'sphinx_copybutton', 'myst_nb', 'jupyter_book', 'sphinx_thebe', 'sphinx_comments', 'sphinx_external_toc', 'sphinx.ext.intersphinx', 'sphinx_design', 'sphinx_book_theme', 'sphinxcontrib.bibtex', 'sphinx_jupyterbook_latex', 'sphinx_multitoc_numbering']
+extensions = ['sphinx_togglebutton', 'sphinx_copybutton', 'myst_nb', 'jupyter_book', 'sphinx_thebe', 'sphinx_comments', 'sphinx_external_toc', 'sphinx.ext.intersphinx', 'sphinx_design', 'sphinx_book_theme', 'sphinxcontrib.bibtex', 'sphinx_jupyterbook_latex', 'sphinx_multitoc_numbering',  "sphinxcontrib.mermaid"]
 external_toc_exclude_missing = False
 external_toc_path = '_toc.yml'
 html_baseurl = ''
diff --git a/docs/deployment_braikbservices.md b/docs/deployment_braikbservices.md
@@ -15,7 +15,7 @@ The JWT User & Scope Manager helps to simplify the management of permissions and
 
 **Installation:**
 - Navigate to `APItokenmanager` directory.
-- Install PostgreSQL databse by running the Docker Compose file present inside _docker-postgresql_ folder.
+- Install PostgreSQL database by running the Docker Compose file present inside _docker-postgresql_ folder.
 	- **Important:** You need to create an `.env` file to hold the following information.
 
 		- POSTGRES_USER: PostgreSQL database user name.
@@ -27,7 +27,7 @@ The JWT User & Scope Manager helps to simplify the management of permissions and
 		- DJANGO_SUPERUSER_USERNAME: Username that you will use to login to JWT User & Scope Manager.
 		- DJANGO_SUPERUSER_EMAIL: Email address of the user.
 		- DJANGO_SUPERUSER_PASSWORD: Password of the Django superuser.
-- Assign the environment variables specified below and deploy the application by executing the Docker Compose file, selecting either development (`docker-compose-dev.yml`) or production (`docker-compose-prod.yml`) depending on your environemnt (see {ref}`content:references:sampleenvfilejwtuserscopemanagerapp`).
+- Assign the environment variables specified below and deploy the application by executing the Docker Compose file, selecting either development (`docker-compose-dev.yml`) or production (`docker-compose-prod.yml`) depending on your environment (see {ref}`content:references:sampleenvfilejwtuserscopemanagerapp`).
 	- DB_NAME: Name of the database.
 	- DB_USER: User name.
 	- DB_PASSWORD: Password.
diff --git a/docs/deployment_userinterface.md b/docs/deployment_userinterface.md
@@ -16,7 +16,7 @@ Navigate to the `nextjsUIapp` directory, and perform the tasks described below.
 		```
 		npm install next@latest react@latest react-dom@latest
 		```
-		If you get issue with depenency, add `--legacy-peer-deps` options.
+		If you get issue with dependency, add `--legacy-peer-deps` options.
 	- Installation of the dependencies.
 		```
 		npm install 
@@ -65,7 +65,7 @@ Navigate to the `nextjsUIapp` directory, and perform the tasks described below.
 
 	```{figure} images/brainkbdocs-statistics_structured_box.png
 	:name: brainkbdocs-statistics_structured_box
-	Landing page configuration of structured models and statics cards using `config-home.yaml`.
+	Landing page configuration of structured models and statistics cards using `config-home.yaml`.
 	```
 
 	```{figure} images/brainkbdocs-knowledgebasepage.png
@@ -174,7 +174,7 @@ structuredmodelsbox:
     slug: "evidenceassertionontology"
     title: "Evidence Assertion Ontology"
     description: "A data model designed to represent types and relationships of evidence and assertions."
-    links: "#"
+    links: "https://brain-bican.github.io/models/index_assertion_evidence"
   - name: "GARS model"
     slug: "garsmodel"
     title: "Annotation Registry Service (GARS)"
@@ -333,5 +333,9 @@ pages:
 	More information regarding these callbacks can be obtained from NextJS website at 
 	[https://next-auth.js.org/providers](https://next-auth.js.org/providers).
 
+  ```{important}
+  We have replaced Google-based authentication with ORCID-based authentication. This note has been retained for reference purposes, as future activation of Google-based authentication might encounter similar issues.
+  ```
+
 - 
 
diff --git a/docs/images/brainkb_rapid_release.png b/docs/images/brainkb_rapid_release.png
diff --git a/docs/images/data-release.png b/docs/images/data-release.png
diff --git a/docs/images/data_release_aws_s3_ui_mapping.png b/docs/images/data_release_aws_s3_ui_mapping.png
diff --git a/docs/images/home.png b/docs/images/home.png
diff --git a/docs/images/login.png b/docs/images/login.png
diff --git a/docs/index.md b/docs/index.md
@@ -10,7 +10,7 @@ This document is currently under development. The content is expected to undergo
 This book is also expected to replace the [BrainKB design document](https://github.com/sensein/brainkb-design-document/tree/design-doc).
 ```
 
-**Last Updated:** `October 15, 2024`
+**Last Updated:** `February 09, 2025`
 
 ## Purpose of the book
 - **Comprehensive Resource on BrainKB:** To provide detailed information about BrainKB, including its guiding principles, architecture, and service components.
diff --git a/docs/list_of_libaries.md b/docs/list_of_libaries.md
@@ -9,13 +9,42 @@
 * - Title
   - Link
   - Description
-* - Ingest service
-  - [https://github.com/sensein/BrainKB/tree/ingestion-fapi-skeleton/ingestion_service](https://github.com/sensein/BrainKB/tree/ingestion-fapi-skeleton/ingestion_service)
-  - 
+* - BrainKB
+  - [sensein/BrainKB](https://github.com/sensein/BrainKB)
+  - Source code for different microservice components of BrainKB.
+* - BrainKB UI
+  - [sensein/brainkb-ui](https://github.com/sensein/brainkb-ui)
+  - Source code for the BrainKB user interface ([https://beta.brainkb.org](https://beta.brainkb.org)).
+* - ProvSense
+  - [pypi.org/project/ProvSense](https://pypi.org/project/ProvSense)
+  - A Python library for comparing changes in KGs.
+* - GrobidArticleExtractor
+  - [pypi.org/project/GrobidArticleExtractor](https://pypi.org/project/GrobidArticleExtractor)
+  - A Python library designed to extract and organize content from scientific papers in PDF format.
+* - EviSense
+  - [pypi.org/project/EviSense](https://pypi.org/project/EviSense)
+  - A Python library to extract evidence and rationales for specific terms within documents, including scientific publications. It supports multiple LLM providers (e.g., Ollama and OpenRouter) and allows the use of multiple models for greater flexibility. See the [example](https://github.com/sensein/EviSense/tree/experiment/example) for a demonstration of how to use it.  
+* - SchemaExtractor
+  - [sensein/SchemaExtractor](https://github.com/sensein/SchemaExtractor/tree/dev)
+  - A Python library for extracting and analyzing schemas from knowledge graphs, leveraging llm-based multi-agent autonomous systems for efficient processing and analysis.
 ```
 
+## Ontologies/Schemas
+```{list-table}
+:header-rows: 1
+:name: table_modelsontologies
 
-```{list-table} Additional Software and Libraries Developed for BrainKB
+* - Title
+  - Link
+  - Description
+* - Assertion Evidence Schema
+  - [models/index_assertion_evidence](https://brain-bican.github.io/models/index_assertion_evidence/)
+  - A schema designed to capture assertions, supporting evidence, and provenance information from scientific publications.
+```
+
+## Supporting Software and Libraries
+
+```{list-table}
 :header-rows: 1
 :name: table_additionalsourcecodes
 
@@ -28,4 +57,5 @@
 * - JWT User & Scope Manager
   - [https://github.com/sensein/BrainKB/tree/ingestion-fapi-skeleton/APItokenmanager](https://github.com/sensein/BrainKB/tree/ingestion-fapi-skeleton/APItokenmanager)
   - Web-based tool for simplified user and permission management using JWT tokens, optimized for FastAPI but versatile for any framework.
-```
+```
+
diff --git a/docs/publications.md b/docs/publications.md
@@ -0,0 +1,4 @@
+# Publications
+
+1. **Chhetri, T.R., Halchenko, Y.O., Jarecka, D., Trivedi, P., Ghosh, S., Ray, P. & Ng, L.** (2025). *Bridging the Scientific Knowledge Gap and Reproducibility: A Survey of Provenance, Assertion and Evidence Ontologies*. In *Companion Proceedings of the ACM Web Conference 2025* (to appear). ACM, Sydney, NSW, Australia, April 28-May 2. doi:10.1145/3701716.3715483.
+2. **Chhetri, T.R., Jarecka, D., Trivedi, P., Amin, J., Baker, P., Dehghani, N., Bhandiwad, A., Smith, K., Ray, P., Bishwakarma, P., Ng, L. & Ghosh, S.** (2024). *BrainKB: A large scale knowledge graph infrastructure for neuroscience*. Poster presented at the INCF Neuroinformatics Assembly, 2024.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,5 @@
 jupyter-book
+sphinx-autobuild
+sphinxcontrib-mermaid
 matplotlib
 numpy
