Skip to content

Commit 7f5b339

Browse files
DraTeotsDraTeots
committed
Initial documentation commit
1 parent 2e59d46 commit 7f5b339

26 files changed

+5660
-0
lines changed

‎.github/workflows/documentation.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: Deploy VitePress site to GitHub Pages
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
deploy:
10+
runs-on: ubuntu-latest
11+
permissions:
12+
id-token: write
13+
contents: read
14+
pages: write
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- name: Set up Node.js
19+
uses: actions/setup-node@v3
20+
with:
21+
node-version: '20'
22+
23+
- name: Install dependencies
24+
run: npm install
25+
working-directory: docs
26+
27+
- name: Build VitePress site
28+
run: npm run build
29+
working-directory: docs
30+
31+
- name: Upload artifact
32+
uses: actions/upload-pages-artifact@v3
33+
with:
34+
path: 'docs/.vitepress/dist'
35+
36+
- name: Deploy to GitHub Pages
37+
id: deployment
38+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,3 +205,7 @@ cython_debug/
205205
marimo/_static/
206206
marimo/_lsp/
207207
__marimo__/
208+
209+
.idea/
210+
211+
docs/.vitepress/cache/

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,4 @@
11
# nps-sro-ml
22
Machine Learning for NPS Streaming Readout
3+
4+
[Full documentation](https://jeffersonlab.github.io/nps-sro-ml/)

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
node_modules/
2+
.vitepress/dist/

‎docs/.vitepress/config.mts‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
import markdownItKatex from 'markdown-it-katex';
2+
import { withMermaid } from "vitepress-plugin-mermaid";
3+
import lightbox from "vitepress-plugin-lightbox"
4+
5+
6+
export default withMermaid({
7+
title: 'NPS-SRO-ML',
8+
description: 'Documentation for NPS SRO ML analysis',
9+
base: '/nps-sro-ml/',
10+
11+
// Improved head settings with proper KaTeX styling
12+
head: [
13+
['link', { rel: 'stylesheet', href: 'https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css' }],
14+
['link', { rel: 'icon', type: 'image/png', href: '/favicon.png' }],
15+
['meta', { name: 'viewport', content: 'width=device-width, initial-scale=1.0' }],
16+
],
17+
18+
// Enhanced theme configuration
19+
themeConfig: {
20+
// Logo (create a simple logo and place it in docs/public/)
21+
logo: 'logo.png',
22+
23+
// Improved navigation
24+
nav: [
25+
{ text: 'Home', link: '/' },
26+
{
27+
text: 'Resources',
28+
items: [
29+
{ text: 'Meetings', link: 'https://wiki.jlab.org/cuawiki/index.php/EIC_Meson_SF_Meeting_Material_and_Summaries' },
30+
{ text: 'Data', link: '/data' },
31+
{ text: 'GitHub', link: 'https://github.com/JeffersonLab/nps-sro-ml' }
32+
]
33+
},
34+
],
35+
36+
// Expanded sidebar with better organization
37+
sidebar: [
38+
{
39+
text: 'Getting Started',
40+
collapsed: false, // Ensure this is not collapsed
41+
items: [
42+
{ text: 'About', link: '/' },
43+
]
44+
},
45+
{
46+
text: 'Data',
47+
link: '/data',
48+
items: [
49+
{ text: 'Data Access', link: '/data' },
50+
]
51+
},
52+
{
53+
text: 'Other',
54+
items: [
55+
{ text: 'Resources', link: '/resources' },
56+
{ text: 'Manage website', link: '/manage-website' },
57+
]
58+
}
59+
],
60+
61+
// Footer customization
62+
footer: {
63+
message: 'Released under the MIT License.',
64+
copyright: 'Copyright © 2025 Meson Structure Collaboration'
65+
},
66+
67+
// Social links
68+
socialLinks: [
69+
{ icon: 'github', link: 'https://github.com/JeffersonLab/sro-nps-ml' }
70+
],
71+
72+
// Search configuration
73+
search: {
74+
provider: 'local'
75+
},
76+
77+
// Layout customization for large screens
78+
outline: {
79+
level: [2, 3],
80+
label: 'On this page'
81+
},
82+
83+
// Additional helpful features
84+
editLink: {
85+
pattern: 'https://github.com/JeffersonLab/nps-sro-ml/edit/main/docs/:path',
86+
text: 'Edit this page on GitHub'
87+
},
88+
89+
// Dark/Light theme toggle (enabled by default)
90+
appearance: true
91+
},
92+
93+
// Enable KaTeX for math rendering
94+
markdown: {
95+
config: (md) => {
96+
md.use(markdownItKatex);
97+
md.use(lightbox, {});
98+
}
99+
},
100+
101+
// Fix layout issues on large screens
102+
vite: {
103+
css: {
104+
preprocessorOptions: {
105+
scss: {
106+
additionalData: `
107+
// Add any global SCSS variables here
108+
`
109+
}
110+
}
111+
}
112+
}
113+
});

‎docs/.vitepress/theme/Layout.vue‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<script setup>
2+
import DefaultTheme from "vitepress/theme";
3+
import { onMounted } from "vue";
4+
import { useRouter, useData } from "vitepress";
5+
import mediumZoom from "medium-zoom";
6+
7+
const { Layout } = DefaultTheme;
8+
const router = useRouter();
9+
const { page } = useData();
10+
11+
// Setup medium zoom with the desired options
12+
const setupMediumZoom = () => {
13+
mediumZoom("[data-zoomable]", {
14+
background: "transparent",
15+
});
16+
};
17+
18+
// Apply medium zoom on load
19+
onMounted(setupMediumZoom);
20+
21+
// Subscribe to route changes to re-apply medium zoom effect
22+
router.onAfterRouteChange = setupMediumZoom;
23+
</script>
24+
25+
<template>
26+
<Layout>
27+
<template #sidebar-nav-before v-if="page.frontmatter.layout === 'home'">
28+
<div class="home-sidebar-content">
29+
<!-- Sidebar is now visible on home page -->
30+
</div>
31+
</template>
32+
</Layout>
33+
</template>
34+
35+
<style>
36+
.medium-zoom-overlay {
37+
backdrop-filter: blur(5rem);
38+
}
39+
40+
.medium-zoom-overlay,
41+
.medium-zoom-image--opened {
42+
z-index: 999;
43+
}
44+
</style>

‎docs/.vitepress/theme/components/README.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Histogram Visualization Components
2+
3+
This directory contains Vue components for displaying histograms in VitePress documentation.
4+
5+
## Components
6+
7+
### JsonHistogram
8+
9+
A simple component for embedding individual histograms from JSON files.
10+
11+
**Usage:**
12+
```vue
13+
<JsonHistogram path="/path/to/histogram.json" />
14+
```
15+
16+
**Props:**
17+
- `path` (string, required): Path to the JSON file
18+
- `height` (string): Chart height (default: '400px')
19+
- `showStats` (boolean): Show statistics bar (default: true)
20+
- `title` (string): Override the histogram title
21+
22+
**Example:**
23+
```vue
24+
<JsonHistogram
25+
path="/analysis/campaign-2025-07/eg-kinematics/10x100/inc_e_p.json"
26+
height="350px"
27+
:show-stats="false"
28+
title="Custom Title"
29+
/>
30+
```
31+
32+
### HistogramViewer
33+
34+
An interactive histogram viewer with a dropdown selector for multiple histograms.
35+
36+
**Usage:**
37+
```vue
38+
<HistogramViewer
39+
base-path="/analysis/campaign-2025-07/eg-kinematics/10x100"
40+
energy="10x100"
41+
/>
42+
```
43+
44+
**Props:**
45+
- `basePath` (string, required): Base path to the histogram files
46+
- `energy` (string): Energy configuration label
47+
48+
## JSON Format
49+
50+
Both components expect JSON files with the following structure:
51+
52+
```json
53+
{
54+
"particle": "inc_e",
55+
"variable": "p",
56+
"title": "Incident Electron - p",
57+
"x_label": "P [GeV/c]",
58+
"bins": {
59+
"edges": [9.0, 9.1, 9.2, ...],
60+
"centers": [9.05, 9.15, 9.25, ...],
61+
"counts": [0, 12, 45, ...]
62+
},
63+
"stats": {
64+
"entries": 100000,
65+
"mean": 9.999,
66+
"std": 0.012
67+
}
68+
}
69+
```
70+
71+
## Features
72+
73+
- **Apache ECharts**: Uses ECharts for rendering
74+
- **Dark Mode**: Automatically adapts to VitePress theme
75+
- **Interactive**: Zoom, pan, and hover tooltips
76+
- **Responsive**: Works on all device sizes
77+
- **TypeScript**: Fully typed components
78+
79+
## Installation
80+
81+
These components are automatically registered in `.vitepress/theme/index.ts`:
82+
83+
```typescript
84+
import JsonHistogram from "./components/JsonHistogram.vue";
85+
import HistogramViewer from "./components/HistogramViewer.vue";
86+
87+
export default {
88+
extends: DefaultTheme,
89+
enhanceApp({ app }) {
90+
app.component('JsonHistogram', JsonHistogram);
91+
app.component('HistogramViewer', HistogramViewer);
92+
}
93+
};
94+
```
95+
96+
## Dependencies
97+
98+
Make sure to install ECharts:
99+
100+
```bash
101+
npm install echarts
102+
```

0 commit comments

Comments
 (0)