From 4657502369ce43e67a12747c171fd2c34207062c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Sep 2025 11:04:51 +0000 Subject: [PATCH 1/2] Initial plan From 081579749bf4bd684e7204804af56ed52219944c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sat, 6 Sep 2025 11:21:02 +0000 Subject: [PATCH 2/2] Create comprehensive GitHub Copilot instructions for shared-slides repository Co-authored-by: DanySK <1991673+DanySK@users.noreply.github.com> --- .github/copilot-instructions.md | 154 ++++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..a9267eb --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,154 @@ +# Shared Slides Repository + +This is a library of shared slide content and preprocessing tools for creating educational presentations. The repository provides markdown-based slide content organized by topic (Git, CI, Java, build systems, etc.) and Ruby-based tooling for content generation and PDF creation. + +Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here. + +## Working Effectively + +### Essential Dependencies +Install the following dependencies before working with this repository: +- `sudo apt update && sudo apt install -y ruby hugo poppler-utils inotify-tools google-chrome-stable` +- Ruby 3.2+ (repository specifies 3.4.5 in `.ruby-version` but 3.2+ works) +- Hugo (for serving content in parent repositories) +- Chrome/Chromium (for PDF generation) +- poppler-utils (provides `pdfinfo` for PDF validation) +- inotify-tools (provides `inotifywait` for file watching) + +### Basic Validation +- Check Ruby syntax: `ruby -c preprocess.rb && ruby -c makepdfs.rb` - takes <1 second +- Test preprocessing: `./preprocess.rb` - takes <1 second, processes any `*generator.md` files found +- Check dependencies: `hugo version && pdfinfo -v && which inotifywait && google-chrome-stable --version` + +### Core Functionality +- **Content preprocessing**: `./preprocess.rb` - processes markdown files with generator patterns + - Looks for files ending in `*generator.md` + - Replaces content between `` and `` comments + - Creates `_index.md` files in the same directory + - **NEVER CANCEL**: Always completes in <1 second, but set timeout to 30+ seconds for safety +- **PDF generation**: `./makepdfs.rb ROOT_DIR` - generates PDFs from HTML slides using headless Chrome + - Requires a Git repository with remote URL configured + - Requires built Hugo site with HTML files accessible via HTTP + - **NEVER CANCEL**: Can take 5 seconds to 5 minutes per presentation. Set timeout to 30+ minutes + - Uses Chrome in headless mode with specific flags for consistent rendering + - Automatically detects slide vs document format and saves appropriately +- **Content serving**: `./serve.sh` - serves content with Hugo and watches for changes + - **IMPORTANT**: Must be run from a parent directory containing both `content/` and `shared-slides/` + - Will fail if run directly from this repository (no Hugo configuration present) + +## Usage Patterns + +### This Repository Is A Content Library +- **NOT a standalone Hugo site** - provides shared content for other repositories +- **Intended usage**: Include as a submodule or subdirectory in course/presentation repositories +- **Tested with**: DanySK/Course-DTM-SE-3, unibo-spe/spe-slides, DanySK/Course-Laboratory-of-Software-Systems, apice-at-disi/oop-lab + +### Typical Workflow in Parent Repositories +1. Include this repository as `shared-slides/` subdirectory +2. Create `content/*/generator.md` files with include directives +3. Run `shared-slides/preprocess.rb` to inject content +4. Use Hugo to build and serve the complete site +5. Optionally generate PDFs with `shared-slides/makepdfs.rb` + +### Example Content Integration +```markdown +--- +title: Git Basics +--- + + + + + + +``` + +After running `shared-slides/preprocess.rb`, this becomes a complete slide with injected content. The `write-here-code` variant excludes the warning comment. + +## Validation + +### Always Test Your Changes +- **Preprocessing validation**: Create a test scenario with generator files and verify content injection works +- **Syntax validation**: Run `ruby -c *.rb` to check Ruby syntax +- **Link validation**: GitHub Actions will run markdown link checking automatically +- **Integration testing**: Test with one of the example repositories from the GitHub workflow + +### Manual Testing Scenarios +```bash +# Test preprocessing workflow +mkdir -p /tmp/test/content/example +echo '--- +title: Test +--- + +' > /tmp/test/content/example/generator.md +cd /tmp/test && cp -r [repo-path] shared-slides +shared-slides/preprocess.rb +# Verify _index.md was created with injected content + +# Test no-warning variant +echo ' +' > /tmp/test/content/example/generator.md +shared-slides/preprocess.rb +# Verify _index.md has no warning comment + +# Test PDF generation (requires Git repo and HTML files) +git init && git remote add origin https://github.com/test/test +echo '

Test

' > index.html +shared-slides/makepdfs.rb . +# Check for generated PDF files +``` + +### Expected Timings +- **Preprocessing**: <1 second for typical repositories (measured: 0.06s) +- **PDF generation**: 5-15 seconds per simple page, up to 5 minutes for complex presentations +- **Hugo serving**: Starts in 1-2 seconds +- **Link checking**: 30 seconds to 2 minutes depending on content +- **NEVER CANCEL**: All operations complete quickly but always set timeouts of 60+ seconds for builds and 30+ seconds for PDF generation + +## Repository Structure + +### Content Directories +- `git/` - Git and version control concepts (14 files) +- `ci/` - Continuous Integration topics +- `java/` - Java programming content +- `build-systems/` - Build tools and dependency management +- `devops/` - DevOps practices and containerization +- `containerization/` - Docker and container technologies + +### Key Scripts +- `preprocess.rb` - Content injection processor (main tool) +- `makepdfs.rb` - PDF generation from HTML slides +- `serve.sh` - Hugo development server with file watching +- `.ruby-version` - Specifies Ruby 3.4.5 (but 3.2+ works) + +### Configuration Files +- `.gitmodules` - Git submodule configuration +- `renovate.json` - Dependency update automation +- `.mergify.yml` - Automated PR merging rules + +## Common Tasks + +### Repository Statistics +- **Total markdown files**: 28 +- **Repository size**: ~548KB +- **Content topics**: 6 main categories +- **Primary language**: Ruby + Markdown + +### Working with Content +- **Add new slides**: Create markdown files in appropriate topic directories +- **Test content**: Always run preprocessing to verify include patterns work +- **Validate links**: GitHub Actions automatically checks all markdown links +- **Update dependencies**: Renovate automatically manages updates + +### Troubleshooting +- **serve.sh fails**: Ensure you're running from a directory with Hugo configuration and `content/` folder +- **PDF generation fails**: Check Chrome installation and HTML content accessibility +- **Preprocessing fails**: Verify file paths in include directives are correct +- **Ruby version issues**: Repository specifies 3.4.5 but 3.2+ is sufficient for all functionality + +## CI/CD Information +- **GitHub Actions**: Runs Ruby syntax checking and preprocessing tests +- **Test repositories**: Validates against multiple real-world course repositories +- **Link checking**: Automated validation of all markdown links +- **No build artifacts**: Repository contains only source content and scripts \ No newline at end of file