Skip to content

Commit 90e3a82

Browse files
authoredFeb 24, 2025··
Merge pull request #3 from sensein/docs
Updated Documentation + Github Action
2 parents c5e8ce7 + 1c0d7ed commit 90e3a82

20 files changed

+196
-33
lines changed
 

‎.github/workflows/build_deploy.yml

+6-6
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ jobs:
2222
pages: write
2323
id-token: write
2424
steps:
25-
- uses: actions/checkout@v3
25+
- uses: actions/checkout@v4
2626

2727
# Install dependencies
2828
- name: Set up Python 3.11
@@ -31,15 +31,15 @@ jobs:
3131
python-version: 3.11
3232

3333
- name: Install dependencies
34-
run: |
35-
pip install -r docs/requirements.txt
34+
run: |
35+
pip install -r docs/requirements.txt
3636
3737
# (optional) Cache your executed notebooks between runs
3838
# if you have config:
3939
# execute:
4040
# execute_notebooks: cache
4141
- name: cache executed notebooks
42-
uses: actions/cache@v3
42+
uses: actions/cache@v4
4343
with:
4444
path: docs/_build/.jupyter_cache
4545
key: jupyter-book-cache-${{ hashFiles('requirements.txt') }}
@@ -51,11 +51,11 @@ jobs:
5151
5252
# Upload the book's HTML as an artifact
5353
- name: Upload artifact
54-
uses: actions/upload-pages-artifact@v2
54+
uses: actions/upload-pages-artifact@v3.0.1
5555
with:
5656
path: "docs/_build/html"
5757

5858
# Deploy the book's HTML to GitHub Pages
5959
- name: Deploy to GitHub Pages
6060
id: deployment
61-
uses: actions/deploy-pages@v2
61+
uses: actions/deploy-pages@v4

‎.github/workflows/codespell.yml

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Codespell configuration is within .codespellrc
2+
---
3+
name: Codespell
4+
5+
on:
6+
push:
7+
branches: [main, docs]
8+
pull_request:
9+
branches: [main]
10+
11+
permissions:
12+
contents: read
13+
14+
jobs:
15+
codespell:
16+
name: Check for spelling errors
17+
runs-on: ubuntu-latest
18+
19+
steps:
20+
- name: Checkout
21+
uses: actions/checkout@v4
22+
23+
- name: Annotate locations with typos
24+
uses: codespell-project/codespell-problem-matcher@v1
25+
26+
- name: Run Codespell
27+
uses: codespell-project/actions-codespell@v2
28+
with:
29+
skip: '*.pyc,*.git,*.svg,references.bib'

‎Dockerfile

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
FROM python:3.10-slim
2+
3+
# The container will always run in /docs
4+
WORKDIR /docs
5+
6+
# We won't COPY here, because we rely on the volume mount for local dev.
7+
8+
# Install dependencies
9+
RUN pip install --no-cache-dir -r docs/requirements.txt
10+
11+
EXPOSE 8040
12+
13+
# Start a live server that rebuilds on changes
14+
CMD ["sphinx-autobuild", ".", "_build/html", "--port", "8040", "--host", "0.0.0.0"]

‎README.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,7 @@ This repository contains the Jupyter Book documentation for BrainKB.
55
## Requirements
66

77
```
8-
pip install -U jupyter-book sphinx-autobuild
9-
8+
pip install -r docs/requirements.txt
109
```
1110

1211
## Running
@@ -30,5 +29,7 @@ Build and watch the Jupyter Book on port other than 8000, i.e., the default one.
3029
sphinx-autobuild . _build/html --open-browser --port 8009
3130
```
3231

33-
**Note:** You need to be inside the jupyterbook directory and run the command, otherwise, replace **"."** with appropriate path.
32+
**Note:**
33+
- 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.
34+
- You need to be inside the jupyterbook directory and run the command, otherwise, replace **"."** with appropriate path.
3435

‎docker-compose.yml

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
version: '3.8'
2+
3+
services:
4+
brainkb-jupyterbook:
5+
build: .
6+
ports:
7+
- "8040:8040"
8+
volumes:
9+
- ./docs:/docs
10+
restart: unless-stopped
11+
healthcheck:
12+
test: ["CMD", "curl", "-f", "http://localhost:8040"]
13+
interval: 30s
14+
timeout: 5s
15+
retries: 3
16+
start_period: 10s

‎docs/_config.yml

+12-8
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,30 @@
33

44
title: BrainKB
55
author: Tek Raj Chhetri (tekraj@mit.edu)
6-
logo: logo.png
6+
logo: images/logo.png
77

8-
# Force re-execution of notebooks on each build.
8+
# Force re-execution of notebooks on each build
99
# See https://jupyterbook.org/content/execute.html
1010
execute:
1111
execute_notebooks: force
1212

13-
# Define the name of the latex output file for PDF builds
13+
# Define the name of the LaTeX output file for PDF builds
1414
latex:
1515
latex_documents:
1616
targetname: book.tex
1717

18-
# Add a bibtex file so that we can create citations
18+
# Add a BibTeX file so that we can create citations
1919
bibtex_bibfiles:
2020
- references.bib
2121

22+
# Enable Mermaid in JupyterBook
23+
#https://opencomputinglab.github.io/SubjectMatterNotebooks/diagram/sphinx-diagrammers.html
24+
sphinx:
25+
extra_extensions:
26+
- sphinxcontrib.mermaid
27+
config:
28+
bibtex_reference_style: author_year
29+
2230
# Information about where the book exists on the web
2331
repository:
2432
url: https://github.com/sensein/brainkbdocs # Online location of your book
@@ -30,7 +38,3 @@ repository:
3038
html:
3139
use_issues_button: true
3240
use_repository_button: true
33-
34-
sphinx:
35-
config:
36-
bibtex_reference_style: author_year

‎docs/_toc.yml

+3-1
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,11 @@ parts:
3131
numbered: True
3232
chapters:
3333
- file: benchmark
34-
- caption: Miscellaneous
34+
- caption: Research Outputs and Software Tools
3535
numbered: True
3636
chapters:
3737
- file: list_of_libaries
38+
- file: publications
39+
3840

3941

‎docs/brainkbui.md

+60-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,61 @@
1-
# User Interface Overview
2-
The currently deployment can be accessed at [http://3.149.235.227:3000/](http://3.149.235.227:3000/).
1+
# User Interface Overview
2+
3+
## Overview
4+
5+
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.
6+
7+
**Key Features:**
8+
- **Search**: Allows users to filter and refine queries based on criteria like species, data type, and file size.
9+
- **Interactive Visualizations**: Offers dynamic visual representations of knowledge graphs to enhance understanding and exploration.
10+
- **Collaboration Support**: Facilitates shared exploration and collaboration, such as contributing assertions and evidence.
11+
12+
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.
13+
14+
## Rapid Release
15+
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.
16+
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.
17+
18+
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.
19+
20+
```{mermaid}
21+
sequenceDiagram
22+
actor User
23+
participant UI as User Interface
24+
participant DB as Graph Database
25+
participant S3 as AWS S3 Bucket
26+
27+
rect rgba(230, 210, 231, 0.5)
28+
note right of User: Manual Steps
29+
User ->> DB: Fetch Data from Graph Database
30+
DB -->> User: Data Retrieved
31+
User ->> S3: Upload Data to S3
32+
S3 -->> User: Confirm Upload
33+
end
34+
35+
rect rgba(200, 255, 200, 0.5)
36+
note right of UI: Automated Steps
37+
UI ->> S3: Fetch Data from S3
38+
S3 -->> UI: Data Retrieved
39+
UI ->> UI: Process and Visualize Data
40+
UI ->> User: Display Data for Download
41+
end
42+
```
43+
44+
```{figure} images/data-release.png
45+
:name: brainkb_data_release
46+
BrainKB rapid release page.
47+
```
48+
49+
50+
```{figure} images/brainkb_rapid_release.png
51+
:name: brainkb_data_release_aws_s3_directory_structure
52+
BrainKB rapid release: Organized AWS S3 bucket directory structure for efficient data management.
53+
```
54+
```{figure} images/data_release_aws_s3_ui_mapping.png
55+
:name: brainkb_data_release_aws_s3_ui_mapping
56+
Mapping BrainKB's AWS S3 bucket directory structure to the user interface for streamlined data access and visualization.
57+
```
58+
## Snapshots of UI
359

460
```{figure} images/home.png
561
:name: brainkb_uihome_figure
@@ -9,4 +65,5 @@ BrainKB UI home page.
965
```{figure} images/login.png
1066
:name: brainkb_uilogin_figure
1167
BrainKB UI login page.
12-
```
68+
```
69+

‎docs/conf.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
comments_config = {'hypothesis': False, 'utterances': False}
1010
copyright = '2023'
1111
exclude_patterns = ['**.ipynb_checkpoints', '.DS_Store', 'Thumbs.db', '_build']
12-
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']
12+
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"]
1313
external_toc_exclude_missing = False
1414
external_toc_path = '_toc.yml'
1515
html_baseurl = ''

‎docs/deployment_braikbservices.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ The JWT User & Scope Manager helps to simplify the management of permissions and
1515

1616
**Installation:**
1717
- Navigate to `APItokenmanager` directory.
18-
- Install PostgreSQL databse by running the Docker Compose file present inside _docker-postgresql_ folder.
18+
- Install PostgreSQL database by running the Docker Compose file present inside _docker-postgresql_ folder.
1919
- **Important:** You need to create an `.env` file to hold the following information.
2020

2121
- POSTGRES_USER: PostgreSQL database user name.
@@ -27,7 +27,7 @@ The JWT User & Scope Manager helps to simplify the management of permissions and
2727
- DJANGO_SUPERUSER_USERNAME: Username that you will use to login to JWT User & Scope Manager.
2828
- DJANGO_SUPERUSER_EMAIL: Email address of the user.
2929
- DJANGO_SUPERUSER_PASSWORD: Password of the Django superuser.
30-
- 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`).
30+
- 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`).
3131
- DB_NAME: Name of the database.
3232
- DB_USER: User name.
3333
- DB_PASSWORD: Password.

‎docs/deployment_userinterface.md

+7-3
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Navigate to the `nextjsUIapp` directory, and perform the tasks described below.
1616
```
1717
npm install next@latest react@latest react-dom@latest
1818
```
19-
If you get issue with depenency, add `--legacy-peer-deps` options.
19+
If you get issue with dependency, add `--legacy-peer-deps` options.
2020
- Installation of the dependencies.
2121
```
2222
npm install
@@ -65,7 +65,7 @@ Navigate to the `nextjsUIapp` directory, and perform the tasks described below.
6565

6666
```{figure} images/brainkbdocs-statistics_structured_box.png
6767
:name: brainkbdocs-statistics_structured_box
68-
Landing page configuration of structured models and statics cards using `config-home.yaml`.
68+
Landing page configuration of structured models and statistics cards using `config-home.yaml`.
6969
```
7070

7171
```{figure} images/brainkbdocs-knowledgebasepage.png
@@ -174,7 +174,7 @@ structuredmodelsbox:
174174
slug: "evidenceassertionontology"
175175
title: "Evidence Assertion Ontology"
176176
description: "A data model designed to represent types and relationships of evidence and assertions."
177-
links: "#"
177+
links: "https://brain-bican.github.io/models/index_assertion_evidence"
178178
- name: "GARS model"
179179
slug: "garsmodel"
180180
title: "Annotation Registry Service (GARS)"
@@ -333,5 +333,9 @@ pages:
333333
More information regarding these callbacks can be obtained from NextJS website at
334334
[https://next-auth.js.org/providers](https://next-auth.js.org/providers).
335335

336+
```{important}
337+
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.
338+
```
339+
336340
-
337341

‎docs/images/brainkb_rapid_release.png

1000 KB
Loading

‎docs/images/data-release.png

403 KB
Loading
403 KB
Loading

‎docs/images/home.png

90.4 KB
Loading

‎docs/images/login.png

-173 KB
Loading

‎docs/index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ This document is currently under development. The content is expected to undergo
1010
This book is also expected to replace the [BrainKB design document](https://github.com/sensein/brainkb-design-document/tree/design-doc).
1111
```
1212

13-
**Last Updated:** `October 15, 2024`
13+
**Last Updated:** `February 09, 2025`
1414

1515
## Purpose of the book
1616
- **Comprehensive Resource on BrainKB:** To provide detailed information about BrainKB, including its guiding principles, architecture, and service components.

‎docs/list_of_libaries.md

+35-5
Original file line numberDiff line numberDiff line change
@@ -9,13 +9,42 @@
99
* - Title
1010
- Link
1111
- Description
12-
* - Ingest service
13-
- [https://github.com/sensein/BrainKB/tree/ingestion-fapi-skeleton/ingestion_service](https://github.com/sensein/BrainKB/tree/ingestion-fapi-skeleton/ingestion_service)
14-
-
12+
* - BrainKB
13+
- [sensein/BrainKB](https://github.com/sensein/BrainKB)
14+
- Source code for different microservice components of BrainKB.
15+
* - BrainKB UI
16+
- [sensein/brainkb-ui](https://github.com/sensein/brainkb-ui)
17+
- Source code for the BrainKB user interface ([https://beta.brainkb.org](https://beta.brainkb.org)).
18+
* - ProvSense
19+
- [pypi.org/project/ProvSense](https://pypi.org/project/ProvSense)
20+
- A Python library for comparing changes in KGs.
21+
* - GrobidArticleExtractor
22+
- [pypi.org/project/GrobidArticleExtractor](https://pypi.org/project/GrobidArticleExtractor)
23+
- A Python library designed to extract and organize content from scientific papers in PDF format.
24+
* - EviSense
25+
- [pypi.org/project/EviSense](https://pypi.org/project/EviSense)
26+
- 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.
27+
* - SchemaExtractor
28+
- [sensein/SchemaExtractor](https://github.com/sensein/SchemaExtractor/tree/dev)
29+
- A Python library for extracting and analyzing schemas from knowledge graphs, leveraging llm-based multi-agent autonomous systems for efficient processing and analysis.
1530
```
1631

32+
## Ontologies/Schemas
33+
```{list-table}
34+
:header-rows: 1
35+
:name: table_modelsontologies
1736
18-
```{list-table} Additional Software and Libraries Developed for BrainKB
37+
* - Title
38+
- Link
39+
- Description
40+
* - Assertion Evidence Schema
41+
- [models/index_assertion_evidence](https://brain-bican.github.io/models/index_assertion_evidence/)
42+
- A schema designed to capture assertions, supporting evidence, and provenance information from scientific publications.
43+
```
44+
45+
## Supporting Software and Libraries
46+
47+
```{list-table}
1948
:header-rows: 1
2049
:name: table_additionalsourcecodes
2150
@@ -28,4 +57,5 @@
2857
* - JWT User & Scope Manager
2958
- [https://github.com/sensein/BrainKB/tree/ingestion-fapi-skeleton/APItokenmanager](https://github.com/sensein/BrainKB/tree/ingestion-fapi-skeleton/APItokenmanager)
3059
- Web-based tool for simplified user and permission management using JWT tokens, optimized for FastAPI but versatile for any framework.
31-
```
60+
```
61+

‎docs/publications.md

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Publications
2+
3+
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.
4+
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.

‎docs/requirements.txt

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
jupyter-book
2+
sphinx-autobuild
3+
sphinxcontrib-mermaid
24
matplotlib
35
numpy

0 commit comments

Comments
 (0)
Please sign in to comment.