Skip to content

Commit 3857cac

Browse files
petecheslockpetecheslock
authored
Simplify Release Management with Static YAML Configuration (#109)
* Remove release-info.json and integrate GitHub API for dynamic release information fetching in components generator. Update deploy workflow to include GITHUB_TOKEN for authenticated requests. Signed-off-by: Pete Cheslock <[email protected]> * Refactor component configuration management - Introduced `components-data.yaml` to serve as a single source of truth for component configurations and release information. - Updated `component-configs.js` to load component data from the new YAML file, eliminating the need for dynamic GitHub API calls. - Refactored the components generator to utilize static data from the YAML file, simplifying the documentation generation process. - Removed the `github-api-utils.js` file as its functionality is no longer needed. This change enhances maintainability and reduces complexity in managing component data. Signed-off-by: Pete Cheslock <[email protected]> * Enhance release management and documentation synchronization - Updated the README.md to include detailed instructions for updating to a new release, including an automated sync script. - Modified components-data.yaml to reflect the latest release version and date, ensuring accurate documentation. - Improved the guide generator to fetch content from the specific release version instead of the main branch, aligning documentation with released versions. - Enhanced source callouts in documentation to differentiate between release versions and main branch content. Signed-off-by: Pete Cheslock <[email protected]> * Update deployment workflow and enhance README for release management - Removed the GITHUB_TOKEN environment variable from the deployment workflow to streamline the build process. - Revised the README.md to clarify steps for cutting a new release, including detailed instructions for updating the YAML file and committing changes. - Improved clarity on the manual operations required for syncing and deploying documentation updates. Signed-off-by: Pete Cheslock <[email protected]> * Remove deprecated versioning function from repo-transforms.js to simplify documentation path generation. The function was previously intended for future Docusaurus versioning but is currently unused, allowing for a more straightforward approach to path handling. Signed-off-by: Pete Cheslock <[email protected]> * Update readme with deployment details Signed-off-by: Pete Cheslock <[email protected]> * Enhance documentation and component synchronization - Updated README.md to clarify the synchronization process for components, guides, and community docs, including handling of special tag formats. - Refactored component configuration management in component-configs.js to streamline loading of component and release information from YAML. - Improved components-data.yaml to include version tags for components, ensuring accurate versioning in documentation. - Enhanced sync-release.mjs to transform version tags for specific repositories and update components with the latest release information. Signed-off-by: Pete Cheslock <[email protected]> * Refactor createStandardTransform to utilize ref for versioning - Updated the createStandardTransform function to use 'ref' (version or branch) instead of just 'branch' when transforming content. This change enhances the flexibility of repository configurations by allowing for more accurate versioning in the transformation process. Signed-off-by: Pete Cheslock <[email protected]> * One off transform to fix link transformation Signed-off-by: Pete Cheslock <[email protected]> * Update documentation and component configuration - Revised CONTRIBUTING.md to reflect changes in component configuration file from `component-configs.js` to `components-data.yaml`. - Enhanced README.md to clarify the remote content system, including detailed instructions for syncing and managing components, guides, and community documentation. - Removed the outdated remote-content/README.md file to streamline documentation. - Updated repo-transforms.js with a TODO comment regarding future link fixes after the next llm-d release. Signed-off-by: Pete Cheslock <[email protected]> * Enhance createSourceCallout and content transformation - Updated the createSourceCallout function to accept an optional mainReleaseVersion parameter, allowing for more informative documentation callouts based on version tags. - Added scenarios to differentiate between documentation for version tags with and without the main release version, improving clarity for users. - Modified the generateComponentRemoteSource function to pass the mainReleaseVersion from components data, ensuring accurate versioning in generated content. Signed-off-by: Pete Cheslock <[email protected]> * Update architecture-main.js to sync documentation with specific release versions - Changed the output filename for transformed documentation from `00_architecture.mdx` to `architecture.mdx`. - Implemented synchronization with the specific release version defined in `components-data.yaml`, ensuring that documentation aligns with the released version rather than the main branch. - Updated URL generation to utilize the release version for fetching content, enhancing the accuracy of the documentation transformation process. Signed-off-by: Pete Cheslock <[email protected]> * Remove outdated events from community documentation Signed-off-by: Pete Cheslock <[email protected]> --------- Signed-off-by: Pete Cheslock <[email protected]>
1 parent 4ec9617 commit 3857cac

File tree

15 files changed

+709
-779
lines changed

15 files changed

+709
-779
lines changed

‎CONTRIBUTING.md‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -75,20 +75,21 @@ To sync new content from repositories:
7575

7676
5. **Test** with `npm start`
7777

78-
See [remote-content/README.md](remote-content/README.md) for detailed instructions.
78+
See the "Remote Content System" section in the main [README.md](README.md) for detailed instructions.
7979

8080
### ⚙️ Adding New Components
8181

82-
Components are auto-generated! Just add to `remote-content/remote-sources/component-configs.js`:
82+
Components are auto-generated! Just add to `remote-content/remote-sources/components-data.yaml`:
8383

84-
```javascript
85-
{
86-
name: 'your-component-name',
87-
org: 'llm-d',
88-
branch: 'main',
89-
description: 'Component description',
90-
sidebarPosition: 10
91-
}
84+
```yaml
85+
components:
86+
# ... existing components
87+
- name: your-component-name
88+
org: llm-d
89+
branch: main
90+
description: Component description
91+
category: Core Infrastructure
92+
sidebarPosition: 10
9293
```
9394
9495
## 📋 General Guidelines

‎README.md‎

Lines changed: 146 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,154 @@
22

33
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
44

5-
The site may be previewed at [llm-d.github.io](https://llm-d.github.io/) before it goes live
5+
Site previews are powered by Netlify and can be viewed in the specific PR.
66

7-
If you spot any errors or omissions in the site, please open an issue at [github.com/llm-d/llm-d.github.io](https://github.com/llm-d/llm-d.github.io/issues)
7+
If you spot any errors or omissions in the site, please open an issue at [github.com/llm-d/llm-d.github.io](https://github.com/llm-d/llm-d.github.io/issues).
88

99
## 📋 Documentation Types
1010

1111
This repository contains two types of documentation:
1212

13-
1. **Local Documentation** - Written directly in this repository (blog posts, etc.)
14-
2. **Remote Synced Content** - Automatically synced from other llm-d repositories (architecture docs, guides, component documentation, community docs.)
13+
1. **Local Documentation** - Written directly in this repository (blog posts, landing pages, etc.)
14+
2. **Remote Synced Content** - Automatically synced from other llm-d repositories during build
1515

16-
Most technical documentation is automatically synced from the main [llm-d/llm-d](https://github.com/llm-d/llm-d) repository to ensure accuracy and consistency.
16+
Most technical documentation is automatically synced from source repositories to ensure accuracy and consistency:
17+
- **Architecture docs** (`/docs/architecture/`) - Synced from component repositories
18+
- **User guides** (`/docs/guide/`) - Synced from the main llm-d repository
19+
- **Component docs** (`/docs/architecture/Components/`) - Auto-generated from individual component repos
20+
- **Community docs** (`/docs/community/`) - Synced from the main repository
21+
22+
Files with remote content show a "Content Source" banner at the bottom with links to edit the original source.
1723

1824
## 🔄 Remote Content System
1925

20-
Many docs pages are automatically synced from source repositories using our remote content system:
26+
### How It Works
2127

22-
- **Architecture Documentation** - Synced from component repositories
23-
- **User Guides** - Synced from the main llm-d repository
24-
- **Component Documentation** - Automatically generated from individual component repos
25-
- **Contributing Guidelines** - Synced from the main repository
28+
The remote content system automatically downloads and syncs content from GitHub repositories during the build process:
2629

27-
Files with remote content show a "Content Source" banner at the bottom with links to edit the original source.
30+
1. **Static Configuration** - `remote-content/remote-sources/components-data.yaml` contains:
31+
- Release version information (which tag to sync from)
32+
- List of all components with their descriptions and versions
33+
- Repository locations and metadata
34+
35+
2. **Content Sources** - Individual files in `remote-content/remote-sources/` define:
36+
- Which repositories to sync from
37+
- Where to place the content in the docs
38+
- How to transform the content (fix links, add frontmatter, etc.)
39+
40+
3. **Build Process** - During `npm run build`:
41+
- Downloads content from the configured GitHub repositories
42+
- Applies transformations (fixes relative links, images, adds source attribution)
43+
- Generates final documentation with proper navigation and styling
44+
45+
**Key Feature:** The build process only reads from the committed YAML file - it never makes write operations or modifies your configuration.
46+
47+
### File Structure
48+
49+
```
50+
remote-content/
51+
├── remote-content.js # Main entry point
52+
└── remote-sources/
53+
├── components-data.yaml # 🎯 Release and component data (edit this!)
54+
├── sync-release.mjs # Script to update YAML from GitHub
55+
├── component-configs.js # Utilities to load YAML data
56+
├── utils.js # Content transformation helpers
57+
├── repo-transforms.js # Link/image fixing logic
58+
├── example-readme.js.template # Template for adding new content
59+
├── architecture/ # → docs/architecture/
60+
│ ├── architecture-main.js
61+
│ └── components-generator.js # Auto-generates component pages
62+
├── guide/ # → docs/guide/
63+
│ └── guide-generator.js # Auto-generates guide pages
64+
└── community/ # → docs/community/
65+
├── code-of-conduct.js
66+
├── contribute.js
67+
├── security.js
68+
└── sigs.js
69+
```
70+
71+
### Cutting a New Release
72+
73+
When a new llm-d release is published, update the documentation site:
74+
75+
**Step 1: Update the YAML file**
76+
```bash
77+
cd remote-content/remote-sources
78+
node sync-release.mjs # Fetches latest release from GitHub API
79+
git diff components-data.yaml # Review the changes
80+
```
81+
82+
This script:
83+
- Queries the [GitHub Releases API](https://github.com/llm-d/llm-d/releases/latest)
84+
- Updates release version, date, and URL in the YAML
85+
- Extracts component descriptions from release notes
86+
- Updates component versions in the YAML
87+
88+
**Step 2: Commit and deploy**
89+
```bash
90+
git add components-data.yaml
91+
git commit -m "Update to llm-d vX.Y.Z"
92+
git push # Triggers automatic deployment
93+
```
94+
95+
**What gets updated:**
96+
- Release version, date, and URLs shown on the Components page
97+
- Component descriptions and version tags
98+
- **Components** sync from their individual release tags
99+
- **Guides** sync from the llm-d/llm-d release tag
100+
- **Community docs** always sync from `main` branch (latest)
101+
102+
**Manual updates:** You can also manually edit `components-data.yaml` if needed.
103+
104+
### Adding New Components
105+
106+
To add a new component to the documentation:
107+
108+
**Edit `remote-content/remote-sources/components-data.yaml`:**
109+
```yaml
110+
components:
111+
# ... existing components
112+
- name: llm-d-your-component
113+
org: llm-d
114+
branch: main
115+
description: Description of your component
116+
category: Core Infrastructure
117+
sidebarPosition: 8
118+
```
119+
120+
The component will automatically appear under `/docs/architecture/Components/` on the next build.
121+
122+
### Adding New Content Sources
123+
124+
To add other remote content (non-component):
125+
126+
1. **Copy the template:**
127+
```bash
128+
cp remote-content/remote-sources/example-readme.js.template \
129+
remote-content/remote-sources/DIRECTORY/your-content.js
130+
```
131+
Choose directory: `architecture/`, `guide/`, or `community/`
132+
133+
2. **Edit the configuration** - Update placeholders:
134+
- Repository name
135+
- Output directory
136+
- Page title and description
137+
- Sidebar position
138+
139+
3. **Import in `remote-content/remote-content.js`:**
140+
```javascript
141+
import yourContent from './remote-sources/DIRECTORY/your-content.js';
142+
143+
const remoteContentPlugins = [
144+
// ... existing sources
145+
yourContent,
146+
];
147+
```
148+
149+
4. **Test:**
150+
```bash
151+
npm start
152+
```
28153

29154
### Making Changes to Synced Content
30155

@@ -36,6 +161,16 @@ Files with remote content show a "Content Source" banner at the bottom with link
36161
**For local website content:**
37162
- Follow the standard pull request process below
38163

164+
### Troubleshooting
165+
166+
| Problem | Solution |
167+
|---------|----------|
168+
| Page not appearing | Check that source URL is publicly accessible |
169+
| Build errors | Verify all template placeholders are replaced |
170+
| Links broken | Make sure you're using `createStandardTransform()` |
171+
| Component not showing | Check `components-data.yaml` and repository accessibility |
172+
| Wrong sidebar order | Adjust `sidebarPosition` numbers in configuration |
173+
39174
## BEFORE DOING A PULL REQUEST
40175

41176
1. **Check if content is synced** - Look for "Content Source" banners at the bottom of pages

‎docs/community/events.md‎

Lines changed: 0 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -11,39 +11,6 @@ Stay connected with the llm-d community at meetups, conferences, and workshops.
1111

1212
{(() => {
1313
const events = [
14-
{
15-
month: 'October 2025',
16-
title: 'IBM TechXchange 2025',
17-
location: 'Orlando, FL',
18-
dateText: 'Oct 6-9, 2025',
19-
cost: 'Paid',
20-
href: 'https://www.ibm.com/community/ibm-techxchange-conference/',
21-
sessions: [
22-
{
23-
title: 'Learn how LLM inference goes distributed with llm-d [4324]',
24-
date: 'Mon, Oct 6, 2025',
25-
time: '3:00pm – 3:30pm EDT',
26-
location: 'Lake Louise, Lobby Level, Hilton',
27-
href: 'https://reg.tools.ibm.com/flow/ibm/techxchange25/sessioncatalog/page/sessioncatalog/session/1756952044813001War5',
28-
},
29-
],
30-
},
31-
{
32-
month: 'October 2025',
33-
title: 'All Things Open 2025',
34-
location: 'Raleigh, NC',
35-
dateText: 'Oct 12–14, 2025',
36-
cost: 'Paid',
37-
href: 'https://2025.allthingsopen.org/register',
38-
sessions: [
39-
{
40-
title: 'llm-d: Open Source Infrastructure for Cost-Efficient LLM Deployment at Scale',
41-
date: 'Oct 12–14, 2025',
42-
time: 'TBD',
43-
href: 'https://2025.allthingsopen.org/sessions/llm-d-open-source-infrastructure-for-cost-efficient-llm-deployment-at-scale',
44-
},
45-
],
46-
},
4714
{
4815
month: 'October 2025',
4916
title: 'AMD AI Dev Day 2025',

‎package-lock.json‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@
2727
"docusaurus-lunr-search": "^3.6.0",
2828
"docusaurus-plugin-remote-content": "^4.0.0",
2929
"jest-environment-jsdom": "^29.7.0",
30+
"js-yaml": "^4.1.0",
3031
"jsdom": "^22.1.0",
3132
"prism-react-renderer": "^2.3.0",
3233
"react": "^19.0.0",

‎release-info.json‎

Lines changed: 0 additions & 16 deletions
This file was deleted.

0 commit comments

Comments
 (0)