Skip to content

Commit 44a2172

Browse files
perkiperki
committed
adding doc
1 parent 0a746cb commit 44a2172

11 files changed

Lines changed: 1827 additions & 0 deletions

‎docs/MAINTAIN-DOC.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Documentation Maintenance Guide
2+
3+
This file describes when and how to update the hds-lib-js documentation in `docs/`.
4+
5+
## Structure
6+
7+
```
8+
docs/ (source, in repo)
9+
├── _config.yml # Jekyll configuration for gh-pages
10+
├── _layouts/
11+
│ └── default.html # Custom layout (nav bar, mermaid support)
12+
├── index.md # Home: overview, architecture, export list
13+
├── getting-started.md # Installation, setup, browser/Node usage
14+
├── settings.md # Settings module reference
15+
├── hds-model.md # HDSModel, items, streams, authorizations, event types, datasources
16+
├── app-templates.md # Detailed App Templates guide (Manager, Collector, Invite, Client)
17+
├── localization.md # Localization utilities
18+
├── toolkit.md # StreamsAutoCreate, StreamTools
19+
├── utilities.md # Duration, reminders, errors, logger
20+
└── MAINTAIN-DOC.md # This file (excluded from Jekyll build)
21+
```
22+
23+
On build (`npm run build`), webpack copies docs flat into `dist/` alongside
24+
the JS bundles and test files. `dist/` is the gh-pages branch root — Jekyll
25+
processes it as a single flat site.
26+
27+
## When to update
28+
29+
### Always update docs when:
30+
31+
1. **Adding a new public method/property** to any exported class
32+
- Add it to the relevant section with signature, description, and example
33+
- If it's in appTemplates, update `app-templates.md`
34+
35+
2. **Changing method signatures** (parameters, return types)
36+
- Update the method documentation and any affected code examples
37+
38+
3. **Adding a new module or class**
39+
- Create a new page if warranted, or add a section to the most relevant existing page
40+
- Update `index.md` exports table and architecture diagram
41+
- Add to `_config.yml` nav if it's a new page
42+
43+
4. **Changing the appTemplates flow** (new statuses, new event types, new stream suffixes)
44+
- Update the sequence diagram, state diagrams, and SVG stream structure in `app-templates.md`
45+
46+
5. **Changing CollectorRequest structure** (new properties, new section types)
47+
- Update the data structure diagram and property tables in `app-templates.md`
48+
49+
6. **Adding or changing event types**
50+
- Update the event types table in `app-templates.md` and/or `hds-model.md`
51+
52+
7. **Changing the data model integration** (new HDSModel sub-modules, new item properties)
53+
- Update `hds-model.md`
54+
55+
### No doc update needed for:
56+
57+
- Internal refactoring that doesn't change the public API
58+
- Bug fixes that don't change behavior
59+
- Test changes
60+
- Build/CI changes
61+
62+
## How to update
63+
64+
### Markdown conventions
65+
66+
- Use Jekyll front matter (`---\nlayout: default\ntitle: ...\n---`) on every page
67+
- Use GitHub-Flavored Markdown (GFM)
68+
- Use fenced code blocks with language tags (`javascript`, `typescript`, `bash`)
69+
- Use Mermaid for flow/sequence/state diagrams (```mermaid blocks)
70+
71+
### Diagrams
72+
73+
- **ASCII trees** — Preferred for hierarchical/nested structures (stream structures, data models). They render everywhere, stay narrow, and are easy to edit.
74+
- **Mermaid** — Use for flowcharts, sequence diagrams, state machines. Rendered by GitHub and most Jekyll themes with mermaid support.
75+
- **Avoid inline SVG** — SVG does not render in most Markdown viewers (GitHub, Jekyll). Use ASCII or Mermaid instead.
76+
- Keep diagram source editable (no rasterized images for diagrams).
77+
- **Split complex diagrams** — When an architecture or overview diagram has multiple concerns (e.g., library modules + class relationships), split into separate graphs stacked vertically rather than one dense graph. This improves readability on all screen sizes.
78+
79+
### Code examples
80+
81+
- Every public method should have at least one usage example
82+
- Examples should be copy-pasteable and realistic
83+
- Use `const` and `await` consistently
84+
- Show typical output in comments where helpful
85+
86+
### Adding a new page
87+
88+
1. Create `docs/new-page.md` with Jekyll front matter (`layout: default`, `title: ...`)
89+
2. Add a nav link in `docs/_layouts/default.html`
90+
3. Add link to the table in `docs/index.md`
91+
92+
## Publishing (gh-pages)
93+
94+
The `dist/` directory is a separate git checkout on the `gh-pages` branch.
95+
Docs are copied flat into `dist/` by the webpack build alongside JS bundles.
96+
97+
**Deploy workflow:**
98+
1. `npm run build` — compiles TS, bundles JS, copies docs to `dist/`
99+
2. `npm run deploy` — commits and pushes `dist/` to gh-pages
100+
101+
Jekyll processes the gh-pages branch root. Our custom `_layouts/default.html`
102+
provides the nav bar and mermaid rendering (no remote theme dependency).
103+
104+
**URL structure:** `https://healthdatasafe.github.io/hds-lib-js/{page}`
105+
106+
## Versioning
107+
108+
When the library version changes significantly, consider noting breaking changes at the top of affected pages. The docs track the current `main` branch — there is no versioned documentation (yet).
109+
110+
## Checklist for doc PRs
111+
112+
- [ ] Updated all affected pages
113+
- [ ] Code examples are correct and tested
114+
- [ ] Mermaid diagrams render (check on GitHub preview)
115+
- [ ] Nav links in `_layouts/default.html` are up to date
116+
- [ ] `index.md` exports table is up to date
117+
- [ ] No broken internal links

‎docs/_config.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
title: HDS JavaScript Library
2+
description: Generic toolkit for server and web applications — Health Data Safe
3+
baseurl: /hds-lib-js
4+
5+
# Markdown rendering
6+
markdown: kramdown
7+
kramdown:
8+
input: GFM
9+
syntax_highlighter: rouge
10+
11+
# Force-include build artifacts (Jekyll passes them through as-is)
12+
include:
13+
- hds-lib.js
14+
- hds-lib.js.map
15+
- hds-lib.js.LICENSE.txt
16+
- tests-browser.js
17+
- tests-browser.js.map
18+
- version.json
19+
- tests.html
20+
21+
exclude:
22+
- MAINTAIN-DOC.md
23+
- Gemfile
24+
- Gemfile.lock

‎docs/_layouts/default.html‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8">
5+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6+
<title>{{ page.title }} — {{ site.title }}</title>
7+
<style>
8+
body {
9+
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
10+
color: #24292f;
11+
line-height: 1.6;
12+
margin: 0;
13+
padding: 0;
14+
}
15+
nav {
16+
background: #24292f;
17+
padding: 10px 20px;
18+
display: flex;
19+
flex-wrap: wrap;
20+
align-items: center;
21+
gap: 4px 16px;
22+
}
23+
nav a {
24+
color: #c9d1d9;
25+
text-decoration: none;
26+
font-size: 0.9em;
27+
}
28+
nav a:hover { color: #fff; }
29+
nav .nav-title {
30+
color: #fff;
31+
font-weight: 600;
32+
font-size: 0.95em;
33+
margin-right: 12px;
34+
}
35+
nav .nav-sep { color: #484f58; }
36+
.content {
37+
max-width: 900px;
38+
margin: 0 auto;
39+
padding: 24px 24px 60px;
40+
}
41+
h1 { border-bottom: 1px solid #d0d7de; padding-bottom: 10px; }
42+
h2 { margin-top: 32px; }
43+
h3 { margin-top: 24px; }
44+
a { color: #0969da; text-decoration: none; }
45+
a:hover { text-decoration: underline; }
46+
code {
47+
background: #f6f8fa;
48+
padding: 2px 6px;
49+
border-radius: 4px;
50+
font-size: 0.9em;
51+
}
52+
pre {
53+
background: #f6f8fa;
54+
padding: 16px;
55+
border-radius: 6px;
56+
overflow-x: auto;
57+
line-height: 1.45;
58+
}
59+
pre code { background: none; padding: 0; }
60+
table {
61+
border-collapse: collapse;
62+
width: 100%;
63+
margin: 16px 0;
64+
}
65+
th, td {
66+
border: 1px solid #d0d7de;
67+
padding: 8px 12px;
68+
text-align: left;
69+
}
70+
th { background: #f6f8fa; }
71+
blockquote {
72+
border-left: 4px solid #d0d7de;
73+
margin: 16px 0;
74+
padding: 4px 16px;
75+
color: #656d76;
76+
}
77+
.mermaid { margin: 16px 0; }
78+
</style>
79+
</head>
80+
<body>
81+
<nav>
82+
<a class="nav-title" href="{{ site.baseurl }}/">HDS Lib</a>
83+
<a href="{{ site.baseurl }}/getting-started">Getting Started</a>
84+
<span class="nav-sep">|</span>
85+
<a href="{{ site.baseurl }}/hds-model">Model</a>
86+
<span class="nav-sep">|</span>
87+
<a href="{{ site.baseurl }}/app-templates">App Templates</a>
88+
<span class="nav-sep">|</span>
89+
<a href="{{ site.baseurl }}/settings">Settings</a>
90+
<span class="nav-sep">|</span>
91+
<a href="{{ site.baseurl }}/localization">Localization</a>
92+
<span class="nav-sep">|</span>
93+
<a href="{{ site.baseurl }}/toolkit">Toolkit</a>
94+
<span class="nav-sep">|</span>
95+
<a href="{{ site.baseurl }}/utilities">Utilities</a>
96+
<span class="nav-sep">|</span>
97+
<a href="{{ site.baseurl }}/tests.html">Tests</a>
98+
</nav>
99+
<div class="content">
100+
{{ content }}
101+
</div>
102+
<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
103+
<script>
104+
mermaid.initialize({ startOnLoad: true, theme: 'neutral' });
105+
// Convert ```mermaid code blocks to mermaid divs
106+
document.querySelectorAll('pre code.language-mermaid').forEach(el => {
107+
const div = document.createElement('div');
108+
div.className = 'mermaid';
109+
div.textContent = el.textContent;
110+
el.parentElement.replaceWith(div);
111+
});
112+
mermaid.run();
113+
</script>
114+
</body>
115+
</html>

0 commit comments

Comments
 (0)