defenseunicorns / defenseunicorns/pepr-docs

Use Source Code Snippets from pepr-excellent-examples Instead of README Mirrors

Open
#191 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
6
Forks
1
Avg merge
23h 7m
Merged PRs (30d)
14

Description

## Description

Code snippets in the pepr-excellent-examples README files are manually maintained copies of the actual source code. This creates a maintenance burden and risks the documentation becoming outdated when code changes. The build process should extract code snippets directly from the source files to ensure they're always current.

**Current approach:**
- Example README files contain manually copied code snippets
- Developers must remember to update README snippets when code changes
- No automated verification that README snippets match actual source code
- Risk of documentation drift over time

**Problems:**
- **Manual synchronization required** - Code changes require updating both source files and README snippets
- **Documentation can become stale** - Easy to forget to update README when refactoring code
- **No single source of truth** - Code exists in two places (source files and README)
- **Maintenance overhead** - Double the work for every code change
- **Quality risk** - Users may copy outdated or incorrect code from examples

**Proposed solution:**
Implement automated code snippet extraction during the build process

**Alternative approaches:**
- Use existing tools like `remark-code-import` or similar plugins
- Implement custom Astro/Starlight plugin for code inclusion
- Use GitHub's raw file URLs with fetch during build

## Related Files

- https://github.com/defenseunicorns/pepr-docs/blob/main/scripts/index.mjs (lines 419-485)
- https://github.com/defenseunicorns/pepr-docs/blob/main/scripts/lib/examples-processing.mjs
- https://github.com/defenseunicorns/pepr-excellent-examples (external repository - all example directories)

## Definition of Done

Code snippets from PEXEX that appear in the docs are always up to date.

**Benefits:**
- **Always current documentation** - Code snippets automatically reflect latest source
- **Single source of truth** - Code only exists in source files
- **Reduced maintenance** - No need to manually sync README with code changes
- **Better quality** - Users always get working, up-to-date examples
- **Easier refactoring** - Code changes automatically propagate to documentation

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.