Skip to content

Commit

Permalink
Merge pull request #1 from pogi7/feat/8-create-user-guide
Browse files Browse the repository at this point in the history
Feat/8 create user guide
  • Loading branch information
pogi7 authored Jan 9, 2024
2 parents 5c8d273 + e2a8171 commit d732154
Show file tree
Hide file tree
Showing 129 changed files with 10,447 additions and 7,403 deletions.
43 changes: 43 additions & 0 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
name: Deploy to GitHub Pages

on:
push:
branches:
- master
# Review gh actions docs if you want to further define triggers, paths, etc
# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

permissions:
contents: write

jobs:
deploy:
name: Deploy to GitHub Pages
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
cache: yarn

- name: Install dependencies
run: yarn install --frozen-lockfile
- name: Build website
run: yarn build

# Popular action to deploy to GitHub Pages:
# Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
# Build output to publish to the `gh-pages` branch:
publish_dir: ./build
# The following lines assign commit authorship to the official
# GH-Actions bot for deploys to `gh-pages` branch:
# https://github.com/actions/checkout/issues/13#issuecomment-724415212
# The GH actions bot is used by default if you didn't specify the two fields.
# You can swap them out with your own user credentials.
user_name: github-actions[bot]
user_email: 41898282+github-actions[bot]@users.noreply.github.com
24 changes: 24 additions & 0 deletions .github/workflows/test-deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
name: Test deployment

on:
pull_request:
branches:
- master
# Review gh actions docs if you want to further define triggers, paths, etc
# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
test-deploy:
name: Test deployment
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
cache: yarn

- name: Install dependencies
run: yarn install --frozen-lockfile
- name: Test build website
run: yarn build
12 changes: 0 additions & 12 deletions blog/2019-05-28-first-blog-post.md

This file was deleted.

44 changes: 0 additions & 44 deletions blog/2019-05-29-long-blog-post.md

This file was deleted.

20 changes: 0 additions & 20 deletions blog/2021-08-01-mdx-blog-post.mdx

This file was deleted.

Binary file not shown.
25 changes: 0 additions & 25 deletions blog/2021-08-26-welcome/index.md

This file was deleted.

17 changes: 0 additions & 17 deletions blog/authors.yml

This file was deleted.

13 changes: 13 additions & 0 deletions changelog/2024-01-09-v0.1.0-initial-release/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
slug: initial-release
title: v0.1.0 Initial Release
authors: [levitt]
tags: [oml, vscode]
---

## v0.1.0 Initial Release

![OML Vision Logo](./vision480x96.png)

### Added
- Initial release
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
5 changes: 5 additions & 0 deletions changelog/authors.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
levitt:
name: Aaron Levitt
title: Full Stack Engineer @ NASA JPL
url: https://www.opencaesar.io/contributors/Aaron%20Levitt.html
image_url: https://www.opencaesar.io/assets/img/aaron.jpeg
8 changes: 8 additions & 0 deletions docs/api-documentation/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"label": "API Documentation",
"position": 2,
"link": {
"type": "generated-index",
"description": "API documentation for OML Vision."
}
}
68 changes: 68 additions & 0 deletions docs/api-documentation/config.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
sidebar_position: 2
---

# Config

The config or configuration directory contains the configuration the following API endpoints for the in-memory [Fuseki](https://jena.apache.org/documentation/fuseki2/) RDF triplestore:

- query
- update

<!-- TODO: Change example to opencaesar organization -->
An example of a config directory correctly formatted for OML Vision can be seen [here](https://github.com/pogi7/kepler16b-example/blob/main/src/vision/config/sparqlConfig.json)

## sparqlConfig.json

:::info sparqlConfig.json

Create a `src/vision/config/sparqlConfig.json` file (case-sensitive)

:::

The `src/vision/config/sparqlConfig.json` file is responsible for specifying the query and update API endpoints.

It is formatted as a JSON data structure.

<!-- TODO: Change to opencaesar repo -->
An example of what this looks like is seen below with the source code found [here](https://github.com/pogi7/kepler16b-example/blob/main/src/vision/config/sparqlConfig.json)

```json
{
"queryEndpoint": "http://localhost:3030/tutorial2/sparql",
"updateEndpoint": "http://localhost:3030/tutorial2/update"
}
```

### queryEndpoint

:::danger REQUIRED

```typescript
queryEndpoint: string
```

:::

This string defines the API query endpoint of the in-memory RDF triplestore.

#### Fuseki

<!-- TODO: Change to opencaesar repo -->
This endpoint can usually be found within the `.fuseki.ttl` file under the `sparql` service. An example of how to specify this endpoint can be found [here](https://github.com/pogi7/kepler16b-example/blob/main/.fuseki.ttl#L15)

### updateEndpoint
:::danger REQUIRED

```typescript
updateEndpoint: string
```

:::

This string defines the API update endpoint of the in-memory RDF triplestore.

#### Fuseki

<!-- TODO: Change to opencaesar repo -->
This endpoint can usually be found within the `.fuseki.ttl` file under the `update` service. An example of how to specify this endpoint can be found [here](https://github.com/pogi7/kepler16b-example/blob/main/.fuseki.ttl#L14)
75 changes: 75 additions & 0 deletions docs/api-documentation/gradle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
sidebar_position: 5
---

# Gradle

OML models tend to use Gradle to package dependencies and tasks to manipulate and analyze the model.

:::danger Gradle for Java VSCode Extension

OML Vision requires the [Gradle for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-gradle) VSCode extension.

Read more installation instructions [here](docs/intro#what-youll-need)

:::

## Build

:::info build.gradle

Create a `build.gradle` file (case-sensitive)

:::

In OML Vision, the `build.gradle` file is responsible for:

- Defining tasks to run in OML Vision
- Listens on the `build.gradle` file for any changes.

Examples of correctly formatted `build.gradle` files for OML Vision are found here:

- [Kepler16b build.gradle](https://github.com/pogi7/kepler16b-example/blob/main/build.gradle)
- [Open Source Rover build.gradle](https://github.com/UTNAK/open-source-rover/blob/main/build.gradle)

You can read more about `build.gradle` files [here](https://docs.gradle.org/current/userguide/build_file_basics.html)

## Tasks

A task in Gradle refers to some command or program that Gradle executes.

Generally OML Vision only requires 5 tasks:

- clean (Removes build folder)
- build (Constructs OWL and OML files)
- startFuseki (starts RDF triplestore)
- owlLoad (Loads OWL data into RDF triplestore)
- stopFuseki (stops RDF triplestore)

### Vision Group

OML Vision is asynchronously listening in the `build.gradle` for any changes to the tasks. OML Vision will display any task in the `vision` group in the sidebar.

:::note REGISTERING NEW GRADLE TASKS

New tasks will register once you deactivate then reactive OML Vision. You can do this by clicking the [File Explorer](https://code.visualstudio.com/docs/getstarted/userinterface#_explorer) then clicking the OML Vision extension icon.

:::

**By default, OML Vision displays the `clean` and `build` tasks. Those tasks do not need to be within the `vision` Gradle group.**

:::tip USER INTERFACE

The `vision` gradle corresponds to the `Setup Tasks` section in OML Vision shown in the red boxes.

![Gradle Tasks](./img/gradleTasks.png)

:::

### Running Tasks

You may run tasks in OML Vision either

- By clicking the `Run Task` button in the OML Vision extension under the `Setup Tasks` section
- Running the task using the Gradle wrapper in any terminal.
- An example of this would be running `./gradlew clean`
Binary file added docs/api-documentation/img/correctJavaVersion.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/api-documentation/img/gradleTasks.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/api-documentation/img/portAlreadyUsed.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 8 additions & 0 deletions docs/api-documentation/layouts/_category_.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"label": "Layouts",
"position": 3,
"link": {
"type": "generated-index",
"description": "API documentation for layouts within OML Vision."
}
}
Loading

0 comments on commit d732154

Please sign in to comment.