Skip to content

Commit 9354182

Browse files
robwittmanrobwittman
authored
[DEVOPS-1590] Add docusaurus site (#15)
* Add docusaurus site * Remove unneeded content * Fix pages build * Fix publish step * Add contents:write permissions * Use kernels subdirectory * Trailing slash * Fix site title and tagling * Fill out some more documentation pages * Update docs, remove some unsupported features * Only publish pages updates on merges to main * Pin deployment action * Address some feeback * Indent Rust docs * Update README to remove default notes * More indentation * Link from README directly to docusaurus documentation * Adjust taskfile invocations for building images * Add version requirements for Docker and Taskfile * Test publishing with Github app * Test publishing directly from actions * Deploy directly to pages * Fix syntax for path * Use string not list * Upload build output, not docs directory * Revert back to publishing only on main
1 parent 0329d00 commit 9354182

25 files changed

+22140
-0
lines changed

‎.github/workflows/pages.yml

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
11+
paths:
12+
- '.github/workflows/pages.yml'
13+
- 'docs/**'
14+
15+
jobs:
16+
build:
17+
name: Build the docusaurus site
18+
runs-on: ubuntu-22.04
19+
defaults:
20+
run:
21+
working-directory: docs
22+
steps:
23+
- uses: actions/checkout@v3
24+
- uses: actions/setup-node@v3
25+
with:
26+
node-version: 18
27+
28+
- name: Install dependencies
29+
run: npm install --frozen-lockfile
30+
- name: Build website
31+
run: npm run build
32+
- name: Fix permissions
33+
run: chmod -v -R +rX "./"
34+
- name: Upload Pages artifact
35+
uses: actions/upload-pages-artifact@v2
36+
with:
37+
path: ./docs/build
38+
39+
deploy:
40+
# Add a dependency to the build job
41+
needs: build
42+
if: ${{ github.ref == '/refs/heads/main' }}
43+
44+
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
45+
permissions:
46+
pages: write # to deploy to Pages
47+
id-token: write # to verify the deployment originates from an appropriate source
48+
49+
# Deploy to the github-pages environment
50+
environment:
51+
name: github-pages
52+
url: ${{ steps.deployment.outputs.page_url }}
53+
54+
# Specify runner + deployment step
55+
runs-on: ubuntu-22.04
56+
steps:
57+
- name: Deploy to GitHub Pages
58+
id: deployment
59+
uses: actions/deploy-pages@v2

‎.pre-commit-config.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ repos:
55
- id: trailing-whitespace
66
- id: end-of-file-fixer
77
- id: check-added-large-files
8+
args: ["--maxkb=1000"]
89
- id: check-shebang-scripts-are-executable
910
- id: check-executables-have-shebangs
1011

‎docs/.gitignore

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎docs/README.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Website
2+
3+
This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
4+
5+
For configuration, development guides, and other information, please refer to https://docusaurus.io/docs/installation#running-the-development-server

‎docs/babel.config.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎docs/docs/contributor-guide/_category_.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Contributor Guide",
3+
"position": 4,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Contribute to Noteable Kernels"
7+
}
8+
}

‎docs/docs/contributor-guide/before-you-contribute.md

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
sidebar_position: 1
3+
title: Before Contributing
4+
---
5+
6+
Before beginning to contribute to Noteable kernels, please take some time and read through the documentation. Once you're
7+
comfortable with the tooling and structure, there are a few prerequisites before a pull request can be opened
8+
and reviewed
9+
10+
### Issue Tracking
11+
12+
Before addressing any issues, or possibly creating a new kernel image, discussion must occur on an issue first. If
13+
there isn't an open issue regarding your change, feel free to create one to start a conversation with the project
14+
maintainers. Since these kernels run on the Noteable platform, certain decisions around languages, supported versions,
15+
and other topics must be made before changes can be made.
16+
17+
### Signed Commits
18+
19+
All commits to the `noteable-io/kernels` repository must be signed. If you don't have commit signing setup
20+
on your workstation, please follow [Signing Commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits)
21+
to do so.
22+
23+
24+
All other style and usage guidelines covered in this documentation apply to Pull Requests by all contributors, both
25+
external and internal.

‎docs/docs/faq.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
---
2+
sidebar_position: 4
3+
title: FAQ
4+
---
5+
6+
### Where can I run these kernels?
7+
8+
Kernels built by this project are for use on Noteable. While there may be other
9+
platforms these kernels _can_ run on, it isn't guaranteed, recommended, or supported
10+
11+
### When will language XXX be available?
12+
13+
We welcome contributions to fix issues with existing kernels, as well as inserting new languages!
14+
Head over to the Contributor Guide, discuss your plan and implementation with maintainers, and once
15+
changes are accepted, those kernels are available for use shortly after
16+
17+
### I need a different version of an installed library?
18+
19+
All the packages in these kernels are verified and tested by the team at Noteable. Updates to libraries,
20+
including security patches, are adopted once they're accepted as valid.
21+
22+
If you have a dependency conflict with a package you're installing, you can open an issue
23+
discussing it with maintainers.

‎docs/docs/getting-started/_category_.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Getting Started",
3+
"position": 2,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "Contribute to Noteable Kernels"
7+
}
8+
}

‎docs/docs/getting-started/building-an-image.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
sidebar_position: 3
3+
title: Build a Kernel
4+
---
5+
6+
After making any required modifications to your kernel, the project uses
7+
```shell
8+
docker buildx bake
9+
```
10+
11+
to build the various Docker images. Each kernel can be targeted specifically,
12+
or if needed, any of the configured groups of images can be built together
13+
14+
## Supported Build Targets
15+
| Bake Target | Language | Version | Notes |
16+
|---|---|---|---|
17+
| `python_3_9` | Python | 3.9 | CPU |
18+
| `python_3_10` | Python | 3.10 | CPU |
19+
| `python_3_9_gpu` | Python | 3.9 | GPU |
20+
| `python_3_10_gpu` | Python | 3.10 | GPU |
21+
| `rlang_4_3_0` | R | 4.3.0 | CPU |
22+
23+
## Building a Kernel
24+
25+
Once necessary files have been copied, `bake` can be executed. This will build
26+
the requested target, and any required parent images
27+
28+
#### Python
29+
```
30+
task python:base:copy-files NBL_PYTHON_VERSION=<python_version> IDENTIFIER=base # or base-gpu for GPU images
31+
task python:noteable:copy-files NBL_PYTHON_VERSION=<python_version> IDENTIFIER=base
32+
docker buildx bake ${target}
33+
```
34+
35+
#### R
36+
```
37+
task r:base:copy-files NBL_LANGUAGE_VERSION=<R version>
38+
docker buildx bake ${target}
39+
```

0 commit comments

Comments
 (0)