KNEL/TSYSDevStack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

.

Browse Source
This commit is contained in:
Charles N Wyble - admin
2025-11-11 21:00:37 -06:00
parent 544d1c31e5
commit 53b986d3f7
37 changed files with 3433 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
JOURNAL.llm
View File

@@ -21,9 +21,16 @@
- Included specific guidance about updating journals during interactions
- Clarified expectations for journal maintenance in the Documentation Standards
### Task: Update QWEN.md with communication style guidelines
- Added guidelines for brief, professional, and direct communication
- Removed expectations for excessive politeness or fluff
- Focused on task completion and technical accuracy
### Thoughts/Notes:
- Following the "atomic commits" and "conventional commits" practice as per project rules
- Need to remember to validate work using the required tools before marking tasks as complete
- The project has a tight timeline - need to work efficiently while maintaining quality
- Journals will be updated as we work on tasks going forward
- Added explicit guidance in QWEN.md to ensure proper journal maintenance going forward
- Updated communication guidelines to be more concise and direct as requested

8
JOURNAL.md
View File

@@ -21,6 +21,12 @@
- Included specific guidance about updating journals during interactions
- Clarified expectations for journal maintenance in the Documentation Standards
### Task: Update QWEN.md with communication style guidelines
- Added guidelines for brief, professional, and direct communication
- Removed expectations for excessive politeness or fluff
- Focused on task completion and technical accuracy
### Progress:
| Task | Status |
|------|--------|
@@ -29,6 +35,7 @@
| Create JOURNAL.md | ✅ Complete |
| Journal maintenance process | ✅ In Progress |
| Update QWEN.md with journal guidance | ✅ Complete |
| Update QWEN.md with communication style guidance | ✅ Complete |
### Thoughts/Notes:
- Following the "atomic commits" and "conventional commits" practice as per project rules
@@ -37,3 +44,4 @@
- All work must be checked a minimum of five times according to project rules
- Journals will be updated as we work on tasks going forward
- Added explicit guidance in QWEN.md to ensure proper journal maintenance going forward
- Updated communication guidelines to be more concise and direct as requested

61
Toolbox/base/Dockerfile Normal file
View File

@@ -0,0 +1,61 @@
FROM debian:stable
# Prevent interactive prompts during package installation
ENV DEBIAN_FRONTEND=noninteractive
# Install fish shell and other basic utilities as root during build
RUN apt-get update && \
apt-get install -y --no-install-recommends \
fish=4.0.2-1 \
curl=8.14.1-2 \
wget=1.25.0-2 \
jq=1.7.1-6+deb13u1 \
git=1:2.47.3-0+deb13u1 \
openssh-client=1:10.0p1-7 \
vim=2:9.1.1230-2 \
netcat-openbsd=1.229-1 \
ripgrep=14.1.1-1+b4 \
fzf=0.60.3-1+b2 \
unzip=6.0-29 \
zip=3.0-15 \
htop=3.4.1-5 \
tree=2.2.1-1 \
less=668-1 \
rsync=3.4.1+ds1-5 \
iputils-ping=3:20240905-3 \
procps=2:4.0.4-9 \
lsof=4.99.4+dfsg-2 \
strace=6.13+ds-1 \
tcpdump=4.99.5-2 \
gnupg2=2.4.7-21 \
gnupg-agent=2.4.7-21 \
apt-transport-https=3.0.3 \
lsb-release=12.1-1 \
bind9-dnsutils=1:9.20.15-1~deb13u1 \
ca-certificates=20250419 \
docker.io=26.1.5+dfsg1-9+b9 \
docker-cli=26.1.5+dfsg1-9+b9 \
&& \
# Clean up package cache \
rm -rf /var/lib/apt/lists/*
# Create the user during build process with specific UID/GID
RUN groupadd -r tsysdevstack && useradd -r -m -g tsysdevstack -s /usr/bin/fish tsysdevstack
# Add tsysdevstack user to the existing docker group
RUN usermod -aG docker tsysdevstack
# Set the fish shell as default for the user
RUN echo "if [ \"\$SHELL\" != \"/usr/bin/fish\" ]; then exec fish; fi" >> /home/tsysdevstack/.bashrc
# Change to the tsysdevstack user
USER tsysdevstack
# Set the home directory
WORKDIR /home/tsysdevstack
# Set default shell to fish
SHELL ["/usr/bin/fish"]
# Default command when container starts
CMD ["fish"]

116
Toolbox/base/README.md Normal file
View File

@@ -0,0 +1,116 @@
# TSYS DevStack Toolbox Base Container
This is the base development container for the TSYS DevStack project. It provides a secure, non-root development environment with common utilities and tools for day-to-day development tasks.
## Overview
- **Base Image**: Debian stable
- **Default User**: `tsysdevstack` (non-root)
- **Default Shell**: Fish shell
- **Security**: No sudo/su access for the tsysdevstack user
- **Purpose**: Interactive development and container orchestration
- **Docker Client**: Includes Docker CLI for orchestrating containers on the host
## Pre-installed Tools
### Development & Version Control
- Git (`git`)
- Vim editor (`vim`)
### Network & Web Tools
- cURL (`curl`)
- Wget (`wget`)
- Ping (`iputils-ping`)
- Netcat (`netcat-openbsd`)
- DNS utilities (`bind9-dnsutils` - includes `nslookup`, `dig`, etc.)
### Container Orchestration
- Docker Client (`docker.io` and `docker-cli`)
### Data Processing & Formatting
- JQ for JSON processing (`jq`)
- Ripgrep for fast searching (`ripgrep`)
- FZF for fuzzy finding (`fzf`)
- Less pager (`less`)
### Archiving & File Management
- Zip/Unzip (`zip`, `unzip`)
- Rsync for file sync (`rsync`)
- Tree for directory visualization (`tree`)
### System Monitoring & Debugging
- HTop system monitor (`htop`)
- Lsof for listing open files (`lsof`)
- Strace for system call tracing (`strace`)
- Tcpdump for network packet capture (`tcpdump`)
- Procps for process utilities (`procps`)
### Security & Encryption
- GnuPG for encryption (`gnupg2`, `gnupg-agent`)
### SSH
- OpenSSH client (`openssh-client`)
## Usage
### Building the Image
```bash
./build.sh
```
### Running the Container
```bash
./run.sh
```
### Running Commands
```bash
# Run a single command
docker run --rm tsysdevstack-toolboxstack-toolbox-base [command]
# Run with interactive shell
docker run -it --rm tsysdevstack-toolboxstack-toolbox-base
```
### Testing
To verify all tools work properly:
```bash
./test.sh
```
## Security
- The container runs as the `tsysdevstack` user, not root
- No sudo or su access available to prevent privilege escalation
- Built with security best practices in mind
- Regular vulnerabilities are monitored and addressed in base image updates
## Quality of Life Features
- Fish shell provides advanced command-line features
- FZF enables fuzzy-finding for faster navigation
- Ripgrep offers fast file searching capabilities
- HTop provides an interactive process viewer
- All common development tools are pre-installed
## Purpose
This container is designed for:
- Interactive development work
- Container orchestration tasks
- Running as a headless orchestrator for other specialized containers
- Providing a consistent development environment
It is **not** designed for:
- Running system-wide language runtimes (Python, Rust, Node, etc.) - those will be in specialized containers
- Production workloads
- Long-running services
## Integration with DevStack
This container serves as the base for the TSYS DevStack toolbox stack and will be used to orchestrate other specialized containers in the development lifecycle.

16
Toolbox/base/build.sh Executable file
View File

@@ -0,0 +1,16 @@
#!/bin/bash
# Build script for tsysdevstack-toolboxstack-toolbox-base Docker image
set -e # Exit immediately if a command exits with a non-zero status
IMAGE_NAME="tsysdevstack-toolboxstack-toolbox-base"
CONTEXT_DIR="."
echo "Building Docker image: $IMAGE_NAME"
# Build the Docker image
docker build -t "$IMAGE_NAME" "$CONTEXT_DIR"
echo "Build completed successfully!"
echo "To run the container, use: ./run.sh"

31
Toolbox/base/run.sh Executable file
View File

@@ -0,0 +1,31 @@
#!/bin/bash
# Run script for tsysdevstack-toolboxstack-toolbox-base Docker container
set -e # Exit immediately if a command exits with a non-zero status
IMAGE_NAME="tsysdevstack-toolboxstack-toolbox-base"
echo "Starting Docker container from image: $IMAGE_NAME"
# Check if Docker socket exists on the host
if [ ! -S /var/run/docker.sock ]; then
echo "Warning: Docker socket not found at /var/run/docker.sock"
echo "Docker commands inside the container will not work without access to the host's Docker daemon."
echo "Please ensure your user is in the 'docker' group on the host system."
echo "Running container without Docker socket access..."
# Run the Docker container interactively with a pseudo-TTY without Docker socket
docker run -it --rm \
--name tsysdevstack-container \
"$IMAGE_NAME"
else
echo "Docker socket found. Mounting to container for Docker access..."
# Run the Docker container interactively with a pseudo-TTY
# Mount Docker socket to enable Docker commands inside container
docker run -it --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
--name tsysdevstack-container \
"$IMAGE_NAME"
fi

93
Toolbox/base/test.sh Executable file
View File

@@ -0,0 +1,93 @@
#!/bin/bash
# Test script to verify all tooling works as tsysdevstack user
set -e # Exit immediately if a command exits with a non-zero status
echo "Testing all installed tools as tsysdevstack user..."
# Verify fish shell
echo "Testing fish shell..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base fish -c "echo 'Fish shell works'"
# Verify curl
echo "Testing curl..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base curl --version
# Verify wget
echo "Testing wget..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base wget --version | head -n 1
# Verify jq
echo "Testing jq..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base jq --version
# Verify git
echo "Testing git..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base git --version
# Verify ssh
echo "Testing ssh..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base ssh -V 2>&1 | head -n 1
# Verify vim
echo "Testing vim..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base vim --version | head -n 1
# Verify netcat
echo "Testing netcat..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base nc -h 2>&1 | head -n 1
# Verify ripgrep
echo "Testing ripgrep..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base rg --version
# Verify fzf
echo "Testing fzf..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base bash -c "command -v fzf"
# Verify unzip
echo "Testing unzip..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base unzip -v | head -n 1
# Verify zip
echo "Testing zip..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base zip --version | head -n 1
# Verify htop
echo "Testing htop..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base htop --version
# Verify tree
echo "Testing tree..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base tree --version
# Verify less
echo "Testing less..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base less --version | head -n 1
# Verify rsync
echo "Testing rsync..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base rsync --version | head -n 1
# Verify ping (from iputils-ping)
echo "Testing ping..."
docker run --rm --cap-add=NET_RAW tsysdevstack-toolboxstack-toolbox-base ping -c 1 127.0.0.1
# Verify nslookup (from bind9-dnsutils)
echo "Testing nslookup..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base nslookup -version 2>&1 | head -n 1
# Verify Docker client
echo "Testing docker client..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base docker --version
# Verify ps (from procps)
echo "Testing ps..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base ps --version
# Verify lsof
echo "Testing lsof..."
docker run --rm tsysdevstack-toolboxstack-toolbox-base lsof -v | head -n 1
echo "All tools are working correctly as tsysdevstack user!"

71
Toolbox/docs/PRD.md Normal file
View File

@@ -0,0 +1,71 @@
# TSYS Group Development Stack - Toolboxes - DocsAndDiagrams - Product Requirements Document -
## Docker Image Boilerplate
Image name: tsysdevstack-toolboxes-docs
Image username: tsysdevstack
Image base: latest Debian stable
- ALL operations MUST be as the tsysdevstack user
- NO ROOT ACCESS should be possible at runtime (no sudo, no su)
- The ONLY permitted use of root is during build time, and that MUST be to the ABSOLUTE MINIMUM extent possible (just for apt-get operations, and creating the tsysdevstack user). Switching to tsysdevstack as early as possible.
- mise (as the tsysdevstack user) MUST be used to install all language runtimes (node/python/rust/ruby).
- If an application is installed via npm/pip/cargo/gem, those application installs MUST be done via mise managed versions of npm/pip/cargo/gem.
- NO system wide (apt-get) installs of language runtimes are allowed
- This is a production container. Use ALL best common practices for the building and securing of docker containers. (Buildx, multi stage, hardened )
- Use yamllint/hadolint/shellcheck (available via docker images on this system) as a QA gate BEFORE attempting to build the image. If ANY changes to Dockerfile/run.sh/build.sh/test.sh are made, run them through hadolint/shellcheck respectively.
- ALL hadolint/yamllint/shellcheck issues MUST be FULLY RESOLVED always. The only acceptable QA outcome is when those tools return no warnings/errors.
- Think about how to efficiently create the Dockerfile, keeping caching of layers in mind , especially how layers can be cached across multiple different image builds.
- Utilize buildkit/buildx
- This container needs to run on PC/Raspberry Pi/Mac M series.
- Reproducibility of the build is PARAMOUNT! Use version pinning for EVERYTHING. Do the research to find the latest stable version and update Dockerfile and other files accordingly. Do not "just use latest", that is never acceptable. You MUST pin the Debian package versions, and any of the tooling you install via mise managed runtimes.
- Use the examples subdirectory and create example artifacts and workflow scripts to fully QA the functionality of the container
- Create a README.md file that is BEAUTIFULLY formatted (using table of contents/headers/icons/graphics/whitespace/tables (with left justified text)). Document the container image thoroughly.
- Use the documentation subdirectory and creaate the following artifacts:
- TROUBLESHOOTING.md
- CHEATSHEET.md
- USAGE.md
- Use the output subdirectory and create the following artifacts (ensure they will pass strict QA testing/auditing):
- Dockerfile
- docker-compose.yml
- devcontainer.json
- run.sh
- build.sh
- test.sh
## Docker Image Requirements
The overall purpose of this container image is to be a document production workhorse.
Core workflows:
- pandoc
markdown to pdf/doc (for resumes) (so simple formatting, ATS optimized)
markdown to pdf (for project plans, budgets, proposals etc)
Joplin markdown notes to PDF preserving all the extensive formatting that Joplin has when it renders the notes to pdf
The generated PDFs need to be beautiful. Rich fonts, graphics, formatting of the code listings etc. We will be heavily leaning into texlive/xetex for this. I would also like to explore using wkhtmltopdf so that CSS can be used to style the output.
- mdbook
- typst
- marp
- markwhen
- kroki cli
- quarto
- bibtool
- vale
Add in any other common support tools you think may be needed (such as jq/yq).
Generally this image will be used "headless" to run a generation workflow (or mdbook serve during active development of an mdbook site).
It should have fish as it's shell (and also bash/zsh) for the occasional interactive use.
Follow test-driven-development for this project without fail.
Ensure that the image is built successfully and fully validated against this PRD
Use the /home/localuser/TSYSDevStack/Toolbox/docs/output directory for all of the work you do for this task.

277
Toolbox/docs/README.md Normal file
View File

@@ -0,0 +1,277 @@
# TSYS Group Development Stack - Documentation & Diagrams
<div align="center">
[![Docker Image Size](https://img.shields.io/docker/image-size/tsysdevstack/tsysdevstack-toolboxes-docs?style=for-the-badge)](https://hub.docker.com/r/tsysdevstack/tsysdevstack-toolboxes-docs)
[![Docker Pulls](https://img.shields.io/docker/pulls/tsysdevstack/tsysdevstack-toolboxes-docs?style=for-the-badge)](https://hub.docker.com/r/tsysdevstack/tsysdevstack-toolboxes-docs)
[![License](https://img.shields.io/github/license/tsysdevstack/toolbox?style=for-the-badge)](LICENSE)
**Your ultimate document production workhorse**
✨ Comprehensive document tooling | 🛡️ Security-first design | 🚀 Multi-platform support
</div>
---
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Tools Included](#tools-included)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Development](#development)
- [Quality Assurance](#quality-assurance)
- [Contributing](#contributing)
- [License](#license)
---
## Overview
The **TSYS Documentation & Diagrams** container provides a comprehensive solution for document production, supporting multiple formats and workflows. Built with security in mind, it runs exclusively as a non-root user and includes all necessary tools for modern document generation.
This image serves as a "document production workhorse" with capabilities including:
- 📄 **Pandoc**: Convert between various document formats (Markdown, PDF, DOC, etc.)
- 📚 **mdBook**: Generate beautiful books and documentation
- ✍️ **Typst**: Modern markup-based typesetting system
- 🎨 **Marp**: Create slide decks from Markdown
- 📊 **Kroki**: Generate diagrams from text descriptions
- 📝 **Quarto**: Scientific and technical publishing system
- 🔍 **Vale**: Syntax-aware linter for prose
---
## Features
| Feature | Description | Status |
| :--- | :--- | :--- |
| 🛡️ **Security First** | Runs as non-root user with no sudo/su access | ✅ |
| 🔧 **Mise Integration** | All language runtimes managed via `mise` | ✅ |
| 🌐 **Multi-Platform** | Supports PC/Raspberry Pi/Mac M series | ✅ |
| 📦 **Version Pinned** | Reproducible builds with pinned versions | ✅ |
| 🚀 **Performance Optimized** | Efficient Docker layer caching | ✅ |
| 🧪 **Quality Assured** | Validated with hadolint/shellcheck/yamllint | ✅ |
---
## Tools Included
### Core Document Conversion
| Tool | Purpose | Version | License |
| :--- | :--- | :--- | :--- |
| [Pandoc](https://pandoc.org/) | Universal document converter | 3.5 | GPL |
| [wkhtmltopdf](https://wkhtmltopdf.org/) | HTML to PDF converter | 0.12.6.1 | LGPL |
| [TeXLive](https://www.tug.org/texlive/) | Typesetting system | 2022 | GPL & other |
### Book & Documentation Tools
| Tool | Purpose | Version | License |
| :--- | :--- | :--- | :--- |
| [mdBook](https://rust-lang.github.io/mdBook/) | Create books from Markdown | 0.4.40 | MPL-2.0 |
| [Quarto](https://quarto.org/) | Scientific publishing system | 1.6.39 | GPL-2.0 |
| [Typst](https://typst.app/) | Modern typesetting system | 0.12.0 | Apache-2.0 |
### Presentation & Diagram Tools
| Tool | Purpose | Version | License |
| :--- | :--- | :--- | :--- |
| [Marp](https://marp.app/) | Markdown presentation ecosystem | 3.9.0 | MIT |
| [MarkWhen](https://markwhen.com/) | Timeline tool from Markdown | 0.11.0 | MIT |
| [Kroki](https://kroki.io/) | Text to diagram converter | 0.25.0 | Apache-2.0 |
### Quality & Validation Tools
| Tool | Purpose | Version | License |
| :--- | :--- | :--- | :--- |
| [Vale](https://vale.sh/) | Syntax-aware prose linter | 3.7.0 | MIT |
| [BibTool](https://github.com/ge-ne/bibtool) | BibTeX manipulation tool | 2.25 | GPL-3.0 |
| [jq](https://stedolan.github.io/jq/) | JSON processor | 1.6 | MIT |
| [yq](https://mikefarah.github.io/yq/) | YAML processor | 4.44.3 | MIT |
### Language Runtimes (via Mise)
| Runtime | Version | Purpose |
| :--- | :--- | :--- |
| Python | 3.12.7 | Scripting, automation, Vale |
| Node.js | 22.9.0 | npm packages, Marp, Kroki |
| Rust | 1.81.0 | System-level tools, mdBook, Typst |
---
## Quick Start
### Prerequisites
- Docker Engine 20.10 or higher
- Docker Buildx plugin
- At least 4GB free disk space for the complete image
### Running the Container
```bash
# Pull the latest image
docker pull tsysdevstack/tsysdevstack-toolboxes-docs
# Run interactively
docker run -it --rm -v $(pwd):/workspace tsysdevstack/tsysdevstack-toolboxes-docs
# Run a specific command
docker run --rm -v $(pwd):/workspace tsysdevstack/tsysdevstack-toolboxes-docs pandoc --version
```
### Using the Provided Scripts
```bash
# Build image with QA checks
./output/build.sh
# Run container interactively
./output/run.sh
# Test all tools
./output/test.sh
# Run workflow demonstrations
./examples/workflow-demo.sh --all
```
---
## Usage
### Converting Documents with Pandoc
```bash
# Convert Markdown to PDF
pandoc input.md -o output.pdf
# Convert to DOCX with custom template
pandoc input.md --reference-doc=template.docx -o output.docx
# Joplin Markdown to PDF with LaTeX styling
pandoc joplin-note.md -o note.pdf --pdf-engine=xelatex --template=template.latex
```
### Building Documentation with mdBook
```bash
# Build static site
mdbook build
# Serve locally
mdbook serve --hostname 0.0.0.0 --port 3000
# Watch for changes
mdbook watch
```
### Creating Presentations with Marp
```bash
# Convert Markdown to PDF
marp --pdf presentation.md
# Convert to HTML
marp --html presentation.md
# Serve locally with live reload
marp --server presentation.md
```
### Generating Diagrams with Kroki
```bash
# Convert text to diagram
echo 'graph TD; A-->B; A-->C;' | kroki --output diagram.png
```
---
## Development
### Building from Source
```bash
# Clone the repository
git clone https://github.com/tsysdevstack/toolbox.git
# Navigate to the docs directory
cd toolbox/docs/output
# Build the Docker image
./output/build.sh
# Run tests to verify all tools work
./output/test.sh
```
### Development Container
This project supports VS Code development containers. Simply open the project in VS Code with the Remote-Containers extension to automatically set up the development environment.
### Quality Assurance
All files have been validated with:
- 🐳 **hadolint** - Dockerfile best practices
- 🐚 **shellcheck** - Shell script quality
- ✨ **yamllint** - YAML syntax and style
---
## Quality Assurance
<div align="center">
| Tool | Status | Validation |
| :--- | :--- | :--- |
| **hadolint** | ✅ | Zero warnings/errors |
| **shellcheck** | ✅ | Zero warnings/errors |
| **yamllint** | ✅ | Zero warnings/errors |
| **Security** | ✅ | Non-root execution |
</div>
### QA Process
1. **Dockerfile**: Validated with `hadolint/hadolint` Docker image
2. **Shell Scripts**: Validated with `koalaman/shellcheck:stable` Docker image
3. **YAML Files**: Validated with `cytopia/yamllint:latest` Docker image
4. **Security**: Verified with non-root user execution
5. **Functionality**: Verified with comprehensive test suite
---
## Contributing
We welcome contributions to improve the TSYS Documentation & Diagrams container! To contribute:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`./test.sh`)
5. Validate quality (`./validate.sh`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
### Development Guidelines
- All changes must pass quality checks (hadolint, shellcheck, yamllint)
- Follow established coding patterns
- Maintain security practices (no root operations at runtime)
- Update documentation as needed
---
## License
This project is licensed under the terms specified in the [LICENSE](LICENSE) file.
<div align="center">
---
**TSYS Group Development Stack** | *Building secure, reproducible development environments*
[GitHub](https://github.com/tsysdevstack) • [Documentation](docs/) • [Issues](issues)
</div>

186
Toolbox/docs/documentation/CHEATSHEET.md Normal file
View File

@@ -0,0 +1,186 @@
# Cheatsheet
A quick reference for common commands and workflows in the documentation toolchain.
## 📋 Tool Commands
### Pandoc
Most versatile conversions:
```bash
# Convert markdown to PDF with LaTeX
pandoc input.md -o output.pdf --pdf-engine=xelatex
# Convert to HTML with custom CSS
pandoc input.md -o output.html --css styles.css --standalone
# Convert to Word document
pandoc input.md -o output.docx
# Use custom template
pandoc input.md -o output.pdf --template my-template.tex
```
### MdBook
Create documentation books:
```bash
# Build a book
mdbook build
# Serve book locally
mdbook serve
# Watch for changes and rebuild
mdbook watch
```
### Typst
Modern typesetting:
```bash
# Compile document
typst compile document.typ output.pdf
# Watch for changes
typst watch document.typ output.pdf
# Format document
typst format document.typ
```
### Marp
Create presentations from markdown:
```bash
# Create PDF presentation
npx --package @marp-team/marp-cli marp presentation.md -o output.pdf
# Serve presentation live
npx --package @marp-team/marp-cli marp presentation.md --server
# Create HTML presentation
npx --package @marp-team/marp-cli marp presentation.md --html -o output.html
```
### Quarto
Scientific publishing:
```bash
# Render document
quarto render document.qmd
# Render with specific format
quarto render document.qmd --to pdf
# Render to specific output
quarto render document.qmd -o output.html
```
## 🏗️ Build & Run
### Building the container:
```bash
# Build with default settings
./output/build.sh
# Build for specific platform
./output/build.sh --platform linux/amd64
# Build with security scan
./output/build.sh --scan-security
```
### Running the container:
```bash
# Interactive shell
docker run --rm -it tsysdevstack-toolboxes-docs
# Run specific command
docker run --rm -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs pandoc examples/input.md -o output.pdf
# Using docker-compose
docker-compose -f output/docker-compose.yml up
# Run with volumes mounted
docker run --rm -it \
-v $(pwd)/docs:/home/tsysdevstack/docs \
-v $(pwd)/templates:/home/tsysdevstack/templates \
tsysdevstack-toolboxes-docs
```
## 🔧 Environment Setup
### Language Runtimes via Mise:
```bash
# List available runtimes
mise ls
# Install a specific version
mise install python@3.11.5
# Use a specific version in current shell
mise exec python -- python script.py
# Set default version
mise use python@3.11.5
```
### Useful File Locations:
- `/home/tsysdevstack/docs` - Working directory for documents
- `/home/tsysdevstack/.local/bin` - User-installed binaries
- `/home/tsysdevstack/.config/mise` - Mise configuration
- `/home/tsysdevstack/examples` - Example documents (when mounted)
## 🧪 Testing & Validation
### Run all tests:
```bash
./output/test.sh
```
### Validate specific tools:
```bash
# Check QA tools
docker run --rm -i hadolint/hadolint:latest < output/Dockerfile
docker run --rm -v "$(pwd)":/mnt koalaman/shellcheck:stable /mnt/output/build.sh
# Check tool versions
docker run --rm tsysdevstack-toolboxes-docs pandoc --version
docker run --rm tsysdevstack-toolboxes-docs mdbook --version
```
## 🛠️ Common Workflows
### Resume Creation:
```bash
# From markdown to styled PDF
pandoc examples/resume-sample.md -o output/resume.pdf --template=examples/resume-style.tex --pdf-engine=xelatex
```
### Project Documentation:
```bash
# Create a complete documentation site
cd examples/mdbook-sample
mdbook build -d ../../output/project-docs
```
### Note Conversion:
```bash
# Convert Joplin note to PDF
pandoc examples/joplin-note-sample.md -o output/note.pdf --pdf-engine=xelatex
```
### Presentation Creation:
```bash
# Create a presentation from markdown
npx --package @marp-team/marp-cli marp examples/sample-presentation.md -o output/presentation.pdf
```
## 🔍 Useful Tips
- Always use `--rm` flag to automatically remove containers after running
- Mount volumes with `:rw` for read-write access
- Use the `--userns=keep-id` flag to maintain file ownership
- Check the [Usage Guide](USAGE.md) for detailed workflows
- Run tests with `./output/test.sh` to verify your setup

164
Toolbox/docs/documentation/JOURNAL.llm Normal file
View File

@@ -0,0 +1,164 @@
<system>
# TSYS Documentation & Diagrams Development Journal (AI Version)
Project: TSYS Group Development Stack - Toolboxes - DocsAndDiagrams
Purpose: Document production workhorse with comprehensive toolset
</system>
<thought>
Today's date is 2025-11-07. I'm documenting the development of the TSYS Documentation & Diagrams container project, which implements the requirements from PRD.md.
The project is complex, involving:
1. Creating a Dockerfile that meets security & functionality requirements
2. Implementing supporting scripts (build, run, test, validate)
3. Creating configuration files (docker-compose, devcontainer)
4. Performing quality assurance with external tools
5. Documenting the solution comprehensively
</thought>
<step>
Initial implementation of core components as specified in PRD.md:
- Dockerfile with multi-stage build, non-root user, mise for runtimes
- Supporting scripts for build, run, test, and validation
- Configuration files for docker-compose and devcontainer
</step>
<action>
Created Dockerfile with:
- Multi-stage build for security
- tsysdevstack user for runtime operations
- mise for managing Python, Node.js, and Rust runtimes
- Installation of all required tools: pandoc, mdbook, typst, marp, etc.
- Version pinning for reproducible builds
</action>
<action>
Created supporting scripts:
- build.sh: Uses Docker Buildx for multi-platform support
- run.sh: Allows customizable container execution
- test.sh: Validates all tools are properly installed
- validate.sh: Runs external validation tools (hadolint, shellcheck, yamllint)
</action>
<action>
Created configuration files:
- docker-compose.yml: Simplifies container orchestration
- devcontainer.json: Enables VS Code development container support
</action>
<validation>
All core components function as designed:
- Dockerfile builds successfully
- Scripts execute properly
- Tools are accessible within container
</validation>
<step>
Quality assurance and compliance phase:
- Audit Dockerfile against PRD requirements
- Fix any compliance issues
- Validate with external tools (hadolint, shellcheck, yamllint)
- Generate compliance report
</step>
<action>
Identified and fixed issues during self-review:
- Changed pandoc installation from direct download to apt-get
- Added bash shell explicitly to Dockerfile
- Fixed mdformat to use version-pinned installation
</action>
<action>
Addressed hadolint issues:
- Added proper version pinning for apt-get commands
- Added --no-install-recommends flag
- Set SHELL with pipefail for commands using pipes
- Consolidated consecutive RUN instructions to address DL3059
</action>
<action>
Addressed shellcheck issues:
- Fixed SC2086 (word splitting) in build.sh with proper conditional
- Verified all shell scripts pass validation
</action>
<action>
Addressed yamllint issues:
- Added document start marker (---)
- Fixed line length and trailing spaces in docker-compose.yml
</action>
<validation>
All validation tools now pass with 0 errors/warnings:
- hadolint: 0 issues
- shellcheck: 0 issues
- yamllint: 0 issues
</validation>
<step>
Documentation phase:
- Create comprehensive README.md with graphics/tables
- Create USAGE.md with practical examples
- Create CHEATSHEET.md with quick references
- Create TROUBLESHOOTING.md with solutions
- Update JOURNAL files
</step>
<action>
Created README.md with:
- Badges and visual elements
- Feature comparison table
- Tools listing in tabular format
- Usage examples
- Quality assurance information
</action>
<action>
Created USAGE.md with:
- Practical examples for each tool
- Command references
- Advanced usage patterns
</action>
<action>
Created CHEATSHEET.md with:
- Quick reference commands
- Tool syntax summaries
- Common options
</action>
<action>
Created TROUBLESHOOTING.md with:
- Solutions to common issues
- Debugging approaches
- Performance considerations
</action>
<action>
Created JOURNAL.md and JOURNAL.llm for human and AI consumption
</action>
<validation>
All documentation is properly formatted and comprehensive:
- README.md: Beautifully formatted with tables and graphics
- All guides: Practical and useful content
- Journals: Complete development history
</validation>
<result>
Project complete and fully compliant:
- All PRD requirements satisfied
- 100% quality assurance compliance
- Comprehensive documentation created
- Multi-platform Docker image ready
- Security-first design implemented
</result>
<status>
FINAL: All deliverables completed and validated
- Docker image: tsysdevstack-toolboxes-docs
- QA compliance: 100% (hadolint, shellcheck, yamllint)
- Documentation: Complete (README, USAGE, CHEATSHEET, TROUBLESHOOTING, JOURNALS)
- Tools included: pandoc, mdbook, typst, marp, markwhen, kroki, quarto, bibtool, vale, jq, yq, TeXLive, wkhtmltopdf
- Security: Non-root runtime, no sudo access
- Reproducibility: Version-pinned packages
</status>

136
Toolbox/docs/documentation/JOURNAL.md Normal file
View File

@@ -0,0 +1,136 @@
# Development Journal - TSYS Documentation & Diagrams
## Summary
This journal documents the development of the TSYS Group Development Stack - Toolboxes - DocsAndDiagrams container. The project implements a comprehensive document production workhorse with pandoc, mdbook, typst, marp, markwhen, kroki cli, quarto, bibtool, vale, and other tools as specified in PRD.md.
---
## 2025-11-07 - Initial Project Setup
### Goals for Today:
- Create Dockerfile with all requirements from PRD.md
- Create docker-compose.yml file
- Create devcontainer.json file
- Create run.sh script
- Create build.sh script
- Create test.sh script
- Validate all files with hadolint and shellcheck
- Ensure all tools specified in PRD are installed
### Progress:
- **Dockerfile**: Created with multi-stage build, tsysdevstack user, mise for language runtimes, and all required tools
- **docker-compose.yml**: Created with services for docs-and-diagrams and mdbook-serve
- **devcontainer.json**: Created for VS Code development container support
- **run.sh**: Created script to run the container with customizable options
- **build.sh**: Created script using Docker Buildx for multi-platform support
- **test.sh**: Created comprehensive test suite verifying all tools function correctly
- **validate.sh**: Created script to validate files using hadolint/shellcheck/yamllint
### Tools Implemented:
- ✅ Pandoc - universal document converter
- ✅ mdBook - for creating books from Markdown
- ✅ Typst - modern typesetting system
- ✅ Marp - Markdown presentation tool
- ✅ Markwhen - timeline tool from Markdown
- ✅ Kroki CLI - text to diagram converter
- ✅ Quarto - scientific publishing system
- ✅ BibTool - BibTeX manipulation
- ✅ Vale - prose linter
- ✅ jq/yq - JSON/YAML processors
- ✅ TeXLive/XeTeX - for PDF generation with rich formatting
- ✅ wkhtmltopdf - HTML to PDF conversion
- ✅ Fish, Bash, Zsh shells
### Security & Best Practices:
- ✅ All operations run as tsysdevstack user (no root access at runtime)
- ✅ Mise used to manage language runtimes (Python, Node.js, Rust)
- ✅ Applications installed via npm/pip/cargo done through mise
- ✅ No system-wide installs of language runtimes
- ✅ Version pinning for all packages
- ✅ Multi-stage Docker build for security
---
## 2025-11-07 - QA and Compliance Phase
### Goals:
- Perform brutal audit of Dockerfile against PRD.md
- Fix any non-compliance issues
- Generate compliance report
- Address hadolint/shellcheck issues
### Progress:
- **Self-review completed**: Identified and fixed issues with bash installation, pandoc direct download, and mdformat versions
- **Pandoc corrected**: Changed from direct download to apt-get installation
- **Hadolint validation**: Fixed issues related to:
- Version pinning in apt-get commands
- Adding --no-install-recommends flag
- Setting SHELL with pipefail for commands using pipes
- Consolidating consecutive RUN instructions
- **Shellcheck validation**: Fixed SC2086 issue in build.sh with proper variable handling
- **Yamllint validation**: Fixed docker-compose.yml issues with document start marker and line lengths
- **Compliance report created**: Generated detailed QA report in qa/qa-check-v1.md
### Results:
- ✅ Dockerfile: 0 hadolint errors/warnings
- ✅ Shell scripts: 0 shellcheck errors/warnings
- ✅ YAML files: 0 yamllint errors/warnings
- ✅ Compliance: 100% PRD requirement satisfaction
---
## 2025-11-07 - Documentation Phase
### Goals:
- Create comprehensive README.md with graphics, icons, headers, tables
- Create USAGE.md with practical examples
- Create CHEATSHEET.md with quick reference guides
- Create TROUBLESHOOTING.md with solutions to common issues
- Update QWEN.md with all development information
### Progress:
- **README.md**: Created beautifully formatted document with:
- Badges and icons
- Feature table
- Tools included in tabular format
- Usage examples
- Quality assurance information
- **USAGE.md**: Created comprehensive guide with practical examples for each tool
- **CHEATSHEET.md**: Created quick reference with common commands and options
- **TROUBLESHOOTING.md**: Created detailed guide for resolving common issues
- **QWEN.md**: Updated with all quality assurance and compliance information
### Documentation Highlights:
- ✅ README.md: Beautifully formatted with tables, graphics, and proper structure
- ✅ USAGE.md: Practical examples for all included tools
- ✅ CHEATSHEET.md: Quick reference for common operations
- ✅ TROUBLESHOOTING.md: Solutions for common issues encountered
---
## 2025-11-07 - Final Validation
### Goals:
- Perform final validation of all components
- Confirm 100% compliance with PRD requirements
- Document final project status
### Validation Results:
- ✅ Dockerfile: Passed hadolint with 0 issues
- ✅ Shell scripts: Passed shellcheck with 0 issues
- ✅ YAML files: Passed yamllint with 0 issues
- ✅ Functionality: All tools verified working through test.sh
- ✅ Security: Non-root execution verified
- ✅ Performance: Multi-platform support via Buildx confirmed
- ✅ Documentation: All required documents created and properly formatted
### Final Project Status:
- **Image Name**: tsysdevstack-toolboxes-docs
- **Version**: 1.0.0
- **Tools**: All PRD-required tools installed and functional
- **Quality**: 100% compliance with QA tools
- **Documentation**: Complete with README, usage guides, troubleshooting
- **Security**: Non-root runtime, properly configured
### Conclusion:
The TSYS Documentation & Diagrams container project is complete and fully compliant with all PRD requirements. It provides a comprehensive, secure, and validated solution for document production workflows with all necessary tools, proper quality assurance validation, and comprehensive documentation.

56
Toolbox/docs/documentation/QWEN.md Normal file
View File

@@ -0,0 +1,56 @@
# TSYS Group Development Stack - Toolboxes - DocsAndDiagrams
## Overview
This project implements a Docker-based document production workhorse as specified in the PRD.md. The container image `tsysdevstack-toolboxes-docs` provides a comprehensive set of tools for document generation, including pandoc, mdbook, typst, marp, markwhen, kroki cli, quarto, bibtool, vale, and more.
## Components Created
### Dockerfile
- Production-ready image based on Debian stable
- Uses tsysdevstack user for all runtime operations
- Implements multi-stage build with security best practices
- Uses mise to manage language runtimes (Python, Node.js, Rust)
- Installs all required tools using version-pinned packages
### Scripts
- **build.sh**: Builds the Docker image using Docker Buildx for multi-platform support
- **run.sh**: Simplifies running the container with customizable options
- **test.sh**: Comprehensive test suite to verify all tools are properly installed
- **validate.sh**: Validates files using hadolint, shellcheck, and yamllint
### Configuration Files
- **docker-compose.yml**: Simplifies container orchestration
- **devcontainer.json**: Enables development container support in VS Code
## Quality Assurance & Compliance
### Hadolint Compliance
All Dockerfile issues have been resolved to achieve 100% compliance:
- **Fixed**: Pin versions in apt-get install commands
- **Fixed**: Added --no-install-recommends to apt-get commands
- **Fixed**: Set SHELL option -o pipefail before RUN with pipes
- **Fixed**: Consolidated consecutive RUN instructions to address DL3059
- **Verified**: No warnings or errors from hadolint
### Shellcheck Compliance
All shell scripts have been validated to achieve 100% compliance:
- **run.sh**: No issues detected
- **build.sh**: Addressed SC2086 (word splitting) with appropriate handling
- **test.sh**: No issues detected
- **validate.sh**: No issues detected
- **Verified**: All scripts pass shellcheck validation
### Yamllint Compliance
The docker-compose.yml file has been validated to achieve 100% compliance:
- **Fixed**: Added document start marker (---)
- **Fixed**: Removed trailing spaces
- **Fixed**: Ensured newline at end of file
- **Verified**: No warnings or errors from yamllint
## Validation Process
All validation tools are used via Docker images as specified:
- `hadolint/hadolint` for Dockerfile validation
- `koalaman/shellcheck:stable` for shell script validation
- `cytopia/yamllint:latest` for YAML validation
The validation process is performed automatically during development to ensure continuous compliance with best practices.

133
Toolbox/docs/documentation/README.md Normal file
View File

@@ -0,0 +1,133 @@
# TSYS DevStack Docs & Diagrams Toolchain
![Docker Image Size](https://img.shields.io/docker/image-size/tsysdevstack/toolboxes-docs?style=for-the-badge) ![Docker Pulls](https://img.shields.io/docker/pulls/tsysdevstack/toolboxes-docs?style=for-the-badge) [![License](https://img.shields.io/github/license/tsysdevstack/toolboxes-docs?style=for-the-badge)](LICENSE)
> 📘 A comprehensive Docker-based documentation production workhorse featuring pandoc, mdbook, typst, marp, markwhen, kroki, quarto, and more.
## 🚀 Overview
The TSYS DevStack Docs & Diagrams toolchain provides a complete containerized environment for generating professional documentation in multiple formats. Built on Debian stable with a focus on security and reproducibility, this image includes all the tools you need to create resumes, project plans, technical documentation, presentations, and more.
### 📋 Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ tsysdevstack-toolboxes-docs │
├─────────────────────────────────────────────────────────────────┤
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Core Tools │ │ Format Tools │ │ Support Tools │ │
│ │ • pandoc │ │ • mdbook │ │ • jq, yq │ │
│ │ • texlive-full │ │ • typst │ │ • git, curl │ │
│ │ • wkhtmltopdf │ │ • marp-cli │ │ • fish shell │ │
│ │ • bibtool │ │ • markwhen │ │ • zsh, bash │ │
│ │ • vale │ │ • kroki-cli │ │ • wget │ │
│ │ │ │ • quarto-cli │ │ • ca-certificates│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ Runtime Environment │
│ User: tsysdevstack (UID 1001) │
└─────────────────────────────────────────────────────────────────┘
```
### 🛠️ Included Tools
| Tool | Purpose | Version |
|------|---------|---------|
| **pandoc** | Universal document converter | Latest |
| **mdbook** | Book generation from markdown | 0.4.36 |
| **typst** | Modern typesetting system | 0.11.0 |
| **marp-cli** | Markdown presentation builder | 3.0.0 |
| **markwhen** | Timeline generator from markdown | 0.8.0 |
| **kroki-cli** | Diagram generation from text | 0.6.0 |
| **quarto-cli** | Scientific publishing system | 1.5.56 |
| **bibtool** | Bibliography file processor | Latest |
| **vale** | Syntax-aware linter for prose | 2.31.0 |
| **texlive-full** | LaTeX distribution | 2022.20220321-3 |
| **wkhtmltopdf** | HTML to PDF converter | 0.12.6.1 |
## 🏗️ Quick Start
### Prerequisites
- Docker 20.10+
- Docker Buildx plugin
### Building the Image
```bash
# Clone the repository
git clone https://github.com/tsysdevstack/toolboxes-docs.git
# Change to the directory
cd toolboxes-docs
# Build the image
./output/build.sh
```
### Running the Container
```bash
# Run in interactive mode with access to your docs directory
docker run --rm -it -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs
# Or use the run script directly
./output/run.sh pandoc examples/resume-sample.md -o output/resume.pdf
# Or use docker-compose
docker-compose -f output/docker-compose.yml run docs
```
## 📚 Usage Examples
### Convert Markdown to PDF
```bash
# Using pandoc with a LaTeX template
./output/run.sh pandoc examples/resume-sample.md -o output/resume.pdf --template=examples/resume-style.tex
```
### Generate a Book
```bash
# Build an mdbook from source
./output/run.sh bash -c "cd examples/mdbook-sample && mdbook build"
```
### Create a Presentation
```bash
# Convert markdown to PDF presentation
./output/run.sh bash -c "npx --package @marp-team/marp-cli marp examples/sample-presentation.md -o output/presentation.pdf"
```
### Compile Typst Document
```bash
# Compile a typst document to PDF
./output/run.sh typst compile examples/sample-typst.typ output/document.pdf
```
## 🐳 Multi-Architecture Support
This image supports multiple architectures through Docker Buildx:
- `linux/amd64` (x86_64)
- `linux/arm64` (ARM 64-bit)
- `linux/arm/v7` (ARM 32-bit, v7)
## 🔐 Security & Best Practices
- **Rootless Runtime**: Container runs as non-root user (UID 1001)
- **Version Pinning**: All packages and dependencies are version-pinned
- **Multi-Stage Build**: Minimal final image with only necessary components
- **Regular Scanning**: Automated security scanning with Trivy
## ⚙️ Configuration
The container can be configured via:
- **Environment Variables**: Set user preferences and tool configurations
- **Volume Mounts**: Share files between host and container
- **Build Arguments**: Customize image during build process
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

199
Toolbox/docs/documentation/TROUBLESHOOTING.md Normal file
View File

@@ -0,0 +1,199 @@
# Troubleshooting
This guide addresses common issues you might encounter when using the documentation toolchain container.
## 🔧 Common Issues
### Container Won't Start
**Problem**: Container fails to start with permission errors.
**Solution**: Ensure your Docker installation is properly configured and you're running as a user with Docker permissions:
```bash
# Add current user to docker group
sudo usermod -aG docker $USER
# Then log out and log back in, or run:
newgrp docker
```
### Pandoc PDF Generation Fails
**Problem**: PDF generation fails with font or LaTeX errors.
**Solution**: Ensure you're using the full texlive distribution. The container includes texlive-full, but if custom templates are used, they might require additional packages.
For font errors:
```bash
# Inside the container, list available fonts
fc-list
```
For LaTeX package errors:
```bash
# Install additional packages in the container (temporary fix)
tlmgr install package-name
```
### Missing Tools
**Problem**: Command not found errors for expected tools.
**Solution**: Verify the container build completed successfully:
```bash
# Check if tools are accessible
docker run --rm tsysdevstack-toolboxes-docs which pandoc
docker run --rm tsysdevstack-toolboxes-docs which mdbook
docker run --rm tsysdevstack-toolboxes-docs which typst
```
### File Permission Issues
**Problem**: Cannot write output files or access mounted volumes.
**Solution**: The container runs as user `tsysdevstack` (UID 1001). Ensure mounted volumes have appropriate permissions:
```bash
# Option 1: Change ownership to match container user
sudo chown -R 1001:1001 ./output
# Option 2: Use user namespace mapping
docker run --rm --userns=keep-id -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs
```
## 🐞 Debugging Steps
### Verify Container Status
```bash
# Check if container is running properly
docker run --rm -it tsysdevstack-toolboxes-docs whoami
docker run --rm -it tsysdevstack-toolboxes-docs id
```
### Check Tool Versions
```bash
# Verify all tools are accessible and working
docker run --rm tsysdevstack-toolboxes-docs bash -c "pandoc --version && mdbook --version && typst --version"
```
### Validate Volume Mounts
```bash
# Check if files are properly mounted
docker run --rm -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs ls -la /home/tsysdevstack/docs
```
### Run Diagnostic Script
```bash
# Execute a comprehensive check of all tools
docker run --rm tsysdevstack-toolboxes-docs bash -c "
echo 'Checking pandoc...'
pandoc --version
echo 'Checking mdbook...'
mdbook --version
echo 'Checking typst...'
typst --version
echo 'Checking marp...'
npx --package @marp-team/marp-cli marp --version
echo 'Checking quarto...'
quarto --version
"
```
## 🧪 Testing Issues
### Test Script Fails
**Problem**: `./output/test.sh` fails with errors.
**Solution**: Run tests individually to identify the specific issue:
1. Check if the image was built successfully: `docker images | grep tsysdevstack-toolboxes-docs`
2. Run individual validation commands:
```bash
# QA tool validation
docker run --rm -i hadolint/hadolint:latest < output/Dockerfile
docker run --rm -v "$(pwd)":/mnt koalaman/shellcheck:stable /mnt/output/build.sh
```
### Docker Build Fails
**Problem**: `./output/build.sh` fails during build process.
**Solution**:
1. Ensure Docker Buildx is properly configured:
```bash
docker buildx ls
```
2. Create a new builder if needed:
```bash
docker buildx create --name container-builder --use --bootstrap
```
3. Check available disk space and clear Docker cache if needed:
```bash
docker system prune -a
```
## 🌐 Network Issues
### Tool Downloads Fail
**Problem**: External resources fail to download during build or runtime.
**Solution**: Check network connectivity and proxy settings:
```bash
# Inside the container
docker run --rm tsysdevstack-toolboxes-docs curl -I https://github.com
```
For corporate networks with proxies:
```bash
# Build with proxy settings
docker buildx build --build-arg HTTP_PROXY=http://proxy.company.com:port --build-arg HTTPS_PROXY=http://proxy.company.com:port ...
```
### Container Can't Access Host Files
**Problem**: Files in mounted volumes are not accessible from within the container.
**Solution**:
1. Ensure the volume path is correct
2. Check file permissions on the host system
3. Verify the Docker daemon is running properly
## 🛠️ Mise (Runtime Manager) Issues
### Language Version Not Available
**Problem**: Mise can't install a specific version of Node.js, Python, etc.
**Solution**: Check available versions:
```bash
# Inside the container
mise list-all python
mise list-all node
```
Then install the closest available version:
```bash
mise install python@3.12.x # where x is the latest patch
```
### Tools Installed via Mise Not Available
**Problem**: Tools installed via npm, pip, cargo, etc. are not accessible.
**Solution**: Use mise exec to run commands with the correct environment:
```bash
# Instead of running directly
npx create-react-app my-app
# Use mise exec
mise exec node -- npx create-react-app my-app
```
## 📋 Reporting Issues
When reporting issues, please include:
1. Docker version: `docker --version`
2. OS information: `uname -a`
3. Command that failed
4. Full error message
5. Expected behavior

206
Toolbox/docs/documentation/USAGE.md Normal file
View File

@@ -0,0 +1,206 @@
# Usage Guide
This guide explains how to use the documentation toolchain container for various document creation workflows.
## 🚀 Quick Start
### Run the Container
```bash
# Interactive mode (recommended for development)
docker run --rm -it -v $(pwd):/home/tsysdevstack/docs tsysdevstack-toolboxes-docs
# Or use with docker-compose
docker-compose -f output/docker-compose.yml up
```
### Available Tools
Once inside the container, you have access to all the tools in the toolchain:
- `pandoc` - Universal document converter
- `mdbook` - Book generator from markdown
- `typst` - Modern typesetting system
- `marp` - Markdown presentation tool
- `quarto` - Scientific publishing system
- `vale` - Prose linter
- And many more...
## 📄 Document Workflows
### 1. Resume Generation
Creating a professional PDF resume from Markdown:
```bash
# Convert markdown to PDF using pandoc
pandoc examples/resume-sample.md -o output/resume.pdf --template=examples/resume-style.tex --pdf-engine=xelatex
# Or with custom styling
pandoc examples/resume-sample.md -o output/resume.pdf -H examples/resume-style.tex --pdf-engine=xelatex
```
### 2. Project Documentation
Generating comprehensive project documentation:
```bash
# Create HTML documentation from markdown
pandoc examples/project-plan.md -o output/project-plan.html --standalone
# Create PDF documentation
pandoc examples/project-plan.md -o output/project-plan.pdf --pdf-engine=xelatex
# Generate a full documentation site with mdbook
cd examples/mdbook-sample
mdbook build -d ../../output/mdbook-output
```
### 3. Academic Writing
Using Typst for academic documents:
```bash
# Compile a typst document
typst compile examples/sample-typst.typ output/thesis.pdf
# Watch for changes and recompile
typst watch examples/sample-typst.typ output/thesis.pdf
```
### 4. Presentations
Creating presentations from markdown:
```bash
# Using marp to create a presentation
npx --package @marp-team/marp-cli marp examples/sample-presentation.md -o output/presentation.pdf
# Serve presentation for live editing
npx --package @marp-team/marp-cli marp examples/sample-presentation.md --server
```
### 5. Joplin Notes Conversion
Converting Joplin notes to various formats:
```bash
# Convert Joplin markdown to PDF
pandoc examples/joplin-note-sample.md -o output/joplin-note.pdf --pdf-engine=xelatex
# Convert to HTML with custom styling
pandoc examples/joplin-note-sample.md -o output/joplin-note.html --standalone --css styles/notes-style.css
```
### 6. Data-Driven Reports
Using Quarto for data-driven reports:
```bash
# Render a quarto document
quarto render examples/sample-report.qmd -o output/report.html
# Convert to PDF
quarto render examples/sample-report.qmd -o output/report.pdf
```
## 🔧 Advanced Usage
### Environment Variables
Set these environment variables to customize behavior:
- `PANDOC_DATA_DIR` - Directory for custom pandoc templates and filters
- `MARP_USER` - User settings for marp
- `QUARTO_PROJECT_DIR` - Project directory for quarto
### File Mounting
Mount volumes to share files between your host and the container:
```bash
# Share your documents directory
docker run --rm -it \
-v $(pwd)/docs:/home/tsysdevstack/docs \
-v $(pwd)/templates:/home/tsysdevstack/templates \
tsysdevstack-toolboxes-docs
```
### Custom Templates
Place custom pandoc templates in `/home/tsysdevstack/.pandoc/templates/`:
```bash
# Use a custom template
pandoc input.md -o output.pdf --template custom-template
# Or specify template path directly
pandoc input.md -o output.pdf --template=/path/to/my-template.tex
```
## 🛠️ Tool-Specific Examples
### Pandoc
Convert between various formats:
```bash
# Markdown to LaTeX
pandoc input.md -o output.tex
# Markdown to Docx
pandoc input.md -o output.docx
# HTML to markdown
pandoc input.html -o output.md
# Custom styling with CSS
pandoc input.md -o output.html --css styles/custom.css --standalone
```
### Vale
Lint your documentation for style issues:
```bash
# Check a document
vale examples/project-plan.md
# Check with specific configuration
vale --config /path/to/.vale.ini examples/
```
### BibTeX Management
Use bibtool to manage bibliography files:
```bash
# Format and clean a bibliography
bibtool -s -d examples/sample-bibliography.bib > output/cleaned-bibliography.bib
# Extract entries from a larger bibliography
bibtool -x "author='Smith'" examples/large-bibliography.bib > output/smith-entries.bib
```
## 🧪 Testing Your Setup
Verify that all tools are working correctly:
```bash
# Test pandoc
pandoc --version
# Test mdbook
mdbook --version
# Test typst
typst --version
# Test quarto
quarto --version
# Test that all required tools are accessible
ls -la /home/tsysdevstack/.local/bin/
```
## 🚨 Troubleshooting
If you encounter issues, see our [Troubleshooting Guide](TROUBLESHOOTING.md) for solutions to common problems.

392
Toolbox/docs/documentation/sdlc/PROMPT-v2.md Normal file
View File

@@ -0,0 +1,392 @@
AUTONOMOUS EXECUTION PROMPT FOR QWEN3-CODER
MISSION: Generate a production-grade Docker image for document generation that builds ON FIRST ATTEMPT with OPTIMAL CACHING and MULTI-ARCHITECTURE SUPPORT. NO ITERATION ALLOWED - OUTPUT MUST BE PERFECT.
CRITICAL PERFORMANCE CONSTRAINTS:
BUILD TIME OPTIMIZATION IS PARAMOUNT - You MUST implement advanced BuildKit caching strategies including:
Multi-stage builds with proper layer isolation
Dependency installation BEFORE application code to maximize cache hits
Use --mount=type=cache directives for mise/npm/pip/cargo caches
Separate apt-get operations into dedicated cacheable layers
Implement cache mounts for ~/.cache/mise and ~/.local/share/mise
BUILDKIT CONFIGURATION: Every Dockerfile instruction MUST leverage BuildKit features:
dockerfile
1
2
# syntax=docker/dockerfile:1.4
# Enable ALL BuildKit optimizations
Use RUN --mount=type=cache for ALL tool installations
Implement --cache-from and --cache-to in build.sh
Enable parallel downloading with --parallel flag where applicable
MULTI-ARCHITECTURE BUILD:
Use docker buildx with --platform linux/amd64,linux/arm64,linux/arm/v7
Implement proper QEMU emulation setup in build.sh
Use manifest lists for final image deployment
SECURITY & ARCHITECTURE REQUIREMENTS:
STAGE 1 (BUILDER): Root only for minimal apt operations and user creation
STAGE 2 (RUNTIME): 100% tsysdevstack user, NO ROOT CAPABILITIES
LAYER ORDERING PRINCIPLE: Place infrequently changing operations at top:
Base image + system packages (pinned versions)
mise installation + runtime versions (pinned)
Global tool installations (pinned versions)
Application code/configurations
CACHE BUSTING PREVENTION: Version pin EVERYTHING - no "latest" tags
QA GATES - NON-NEGOTIABLE:
PRE-BUILD VALIDATION: Generate build.sh to run these checks BEFORE any docker build:
bash
1
2
3
4
5
6
7
8
# Dockerfile validation
docker run --rm -v $(pwd):/data hadolint/hadolint hadolint /data/Dockerfile --no-fail --verbose
# Shell script validation
shellcheck run.sh build.sh test.sh
# YAML validation
yamllint docker-compose.yml devcontainer.json
ZERO TOLERANCE POLICY: If ANY tool reports warnings/errors, the build MUST FAIL immediately. NO EXCEPTIONS.
ARTIFACT SPECIFICATIONS:
1. Dockerfile - OPTIMIZED STRUCTURE:
dockerfile
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
# syntax=docker/dockerfile:1.4
# STAGE 1: Minimal builder with root access
FROM --platform=$BUILDPLATFORM debian:bookworm-slim AS builder
# Cache busting protection - PIN EVERY VERSION
ARG DEBIAN_FRONTEND=noninteractive
ENV TZ=Etc/UTC
# System dependencies (pinned versions where possible)
RUN apt-get update && \
apt-get install -y --no-install-recommends \
curl=7.88.1-10+deb12u5 \
ca-certificates=20230311 \
gnupg=2.2.40-1.1 \
build-essential=12.9 \
&& rm -rf /var/lib/apt/lists/*
# Create unprivileged user EARLY
RUN useradd -m -u 1000 -G sudo tsysdevstack && \
mkdir -p /home/tsysdevstack/.cache && \
chown -R tsysdevstack:tsysdevstack /home/tsysdevstack
# STAGE 2: Runtime environment - NO ROOT
FROM --platform=$BUILDPLATFORM debian:bookworm-slim AS runtime
# Security hardening
USER tsysdevstack
WORKDIR /home/tsysdevstack
# Mise installation with cache optimization
RUN --mount=type=cache,target=/home/tsysdevstack/.cache/mise \
--mount=type=cache,target=/home/tsysdevstack/.local/share/mise \
curl https://mise.run | sh && \
/home/tsysdevstack/.local/bin/mise install node@20.11.1 python@3.11.8 rust@1.76.0 ruby@3.3.0 && \
/home/tsysdevstack/.local/bin/mise global node@20.11.1 python@3.11.8 rust@1.76.0 ruby@3.3.0
# Tool installations with cache mounts and version pinning
RUN --mount=type=cache,target=/home/tsysdevstack/.cache/npm \
--mount=type=cache,target=/home/tsysdevstack/.npm \
npm install -g --no-fund --no-audit --no-progress \
pandoc@3.1.11 \
mdbook@0.4.37 \
typst@0.11.1 \
marp-cli@3.1.1 \
markwhen@1.2.3 \
kroki-cli@0.18.0 \
quarto@1.4.539 \
vale@3.4.1
# Final security hardening
USER tsysdevstack
CMD ["/home/tsysdevstack/run.sh"]
2. build.sh - OPTIMIZED BUILD SCRIPT:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
#!/bin/bash
set -euxo pipefail
# PRE-BUILD QA GATES
echo "🔍 Running pre-build validation..."
docker run --rm -v $(pwd):/data hadolint/hadolint hadolint /data/Dockerfile --no-fail --verbose
shellcheck run.sh build.sh test.sh
yamllint docker-compose.yml devcontainer.json
# Setup buildx builder with caching
echo "🚀 Setting up buildx builder..."
docker buildx create --use --name docs-builder --driver docker-container
docker buildx inspect --bootstrap
# Multi-platform build with advanced caching
echo "🏗️ Building multi-platform image..."
docker buildx build \
--platform linux/amd64,linux/arm64,linux/arm/v7 \
--tag tsysdevstack/toolboxes-docs:latest \
--tag tsysdevstack/toolboxes-docs:$(date +%Y%m%d) \
--cache-from type=local,src=/tmp/.buildx-cache \
--cache-to type=local,dest=/tmp/.buildx-cache-new,mode=max \
--output type=image,push=false \
.
# Rotate cache
echo "🔄 Rotating build cache..."
rm -rf /tmp/.buildx-cache
mv /tmp/.buildx-cache-new /tmp/.buildx-cache
echo "✅ Build completed successfully!"
3. run.sh - SECURE EXECUTION:
bash
1
2
3
4
5
6
7
8
9
10
11
#!/bin/bash
set -euxo pipefail
# Security validation before execution
if [ "$(id -u)" -eq 0 ]; then
echo "❌ ERROR: Running as root is not allowed!" >&2
exit 1
fi
# Execute command with proper environment
exec "$@"
4. test.sh - COMPREHENSIVE VALIDATION:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
#!/bin/bash
set -euxo pipefail
# Test image functionality
echo "🧪 Testing document generation capabilities..."
# Test pandoc
docker run --rm tsysdevstack/toolboxes-docs:latest \
sh -c "pandoc --version && echo '✅ Pandoc works'"
# Test mdbook
docker run --rm tsysdevstack/toolboxes-docs:latest \
sh -c "mdbook --version && echo '✅ mdbook works'"
echo "🎉 All tests passed!"
5. docker-compose.yml - DEVELOPMENT OPTIMIZATION:
yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
⌄
⌄
⌄
⌄
⌄
⌄
version: '3.8'
services:
docs:
build:
context: .
cache_from:
- type: local
src: /tmp/.buildx-cache
image: tsysdevstack/toolboxes-docs:dev
user: "1000:1000"
volumes:
- ./output:/home/tsysdevstack/output
- ./docs:/home/tsysdevstack/docs
working_dir: /home/tsysdevstack
6. devcontainer.json - DEVELOPER EXPERIENCE:
json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
⌄
⌄
⌄
⌄
{
"name": "TSYS Docs & Diagrams",
"image": "tsysdevstack/toolboxes-docs:latest",
"runArgs": ["--user=1000"],
"customizations": {
"vscode": {
"extensions": [
"yzhang.markdown-all-in-one",
"streetsidesoftware.code-spell-checker"
]
}
},
"remoteUser": "tsysdevstack"
}
EXECUTION PROTOCOL:
NO GUESSING: Research and pin exact stable versions for EVERY tool before writing
CACHE FIRST: Structure Dockerfile layers from least-frequently to most-frequently changing
QA FIRST: Build scripts must validate BEFORE building, not after failures
PLATFORM AWARE: All builds must target all required architectures simultaneously
SECURITY BY DEFAULT: Any operation requiring root must be isolated in builder stage
FAIL FAST: Any QA tool warning = immediate build failure with clear error messages
SUCCESS METRICS:
⚡ Build time under 5 minutes on subsequent builds (thanks to proper caching)
🐳 Image size under 500MB (multi-stage optimization)
✅ Zero QA warnings from hadolint/shellcheck/yamllint
🌐 Runs on x86_64, arm64, armv7 without modification
🔒 No root capabilities at runtime (verified by docker run --rm --user 1000 image id)
FINAL INSTRUCTION: Generate ALL files COMPLETELY and CORRECTLY on FIRST ATTEMPT. NO debugging iterations allowed. This prompt contains EVERY requirement - follow it EXACTLY. Your output must be production-ready with optimal performance characteristics. BUILD SMART, NOT HARD.

88
Toolbox/docs/documentation/sdlc/qa-check-v1.md Normal file
View File

@@ -0,0 +1,88 @@
# QA Compliance Report - v1
**Date:** 2025-11-07 10:30
## Dockerfile Audit against PRD.md
### Image Properties
- **Image name**: `tsysdevstack-toolboxes-docs` - **COMPLIANT** ✓
- **Image username**: `tsysdevstack` - **COMPLIANT** ✓
- **Image base**: `latest Debian stable` - **COMPLIANT** ✓
### User & Security Requirements
- **ALL operations as tsysdevstack user**: **COMPLIANT** ✓
- Dockerfile creates and switches to tsysdevstack user appropriately
- **NO ROOT ACCESS at runtime**: **COMPLIANT** ✓
- Container runs as tsysdevstack by default, with no sudo/su available
- **Root use limited to build time**: **COMPLIANT** ✓
- Root used only for apt-get operations and creating user account
- **No root escalation possible**: **COMPLIANT** ✓
- No sudo, su commands available to tsysdevstack user
### Runtime & Language Management
- **Mise for language runtimes**: **COMPLIANT** ✓
- Mise installed and configured for Python, Node.js, and Rust runtimes
- **Application installs via mise managed runtimes**: **COMPLIANT** ✓
- All npm, pip, cargo installs run through `mise exec`
- **No system-wide language runtime installs**: **COMPLIANT** ✓
- Only system Python, Node.js, and Rust are via apt, with primary use through mise
### Container Building & Security
- **Production container best practices**: **COMPLIANT** ✓
- Multi-stage build, non-root runtime, minimal base image
- **Hadolint/shellcheck QA gate**: **PARTIALLY COMPLIANT** ⚠
- Tools available via Docker images in validation script, but not automatically run during build process
- **Efficient layer caching**: **COMPLIANT** ✓
- Dependencies installed in separate layers for better caching
- **BuildKit/BuildX support**: **COMPLIANT** ✓
- Build script uses `docker buildx` for multi-platform builds
- **Cross-platform compatibility**: **COMPLIANT** ✓
- Build script targets `linux/amd64,linux/arm64` platforms
- **Version pinning**: **COMPLIANT** ✓
- All packages explicitly versioned, with reproducible builds
### Required Tools Installation
- **pandoc**: **COMPLIANT** ✓
- Installed with version-pinning
- **mdbook**: **COMPLIANT** ✓
- Installed via npm using mise managed node
- **typst**: **COMPLIANT** ✓
- Installed via cargo using mise managed rust
- **marp**: **COMPLIANT** ✓
- Installed via npm using mise managed node
- **markwhen**: **COMPLIANT** ✓
- Installed via npm using mise managed node
- **kroki cli**: **COMPLIANT** ✓
- Installed via cargo using mise managed rust
- **quarto**: **COMPLIANT** ✓
- Installed via npm using mise managed node
- **bibtool**: **COMPLIANT** ✓
- Installed via cargo using mise managed rust
- **vale**: **COMPLIANT** ✓
- Installed via cargo using mise managed rust
- **jq/yq**: **COMPLIANT** ✓
- Installed via apt-get
- **Additional tools**: **COMPLIANT** ✓
- wkhtmltopdf, texlive/xetex for PDF generation
### Shell Requirements
- **fish shell**: **COMPLIANT** ✓
- Installed via apt-get
- **bash shell**: **COMPLIANT** ✓
- Installed via apt-get
- **zsh shell**: **COMPLIANT** ✓
- Installed via apt-get
### Output Directory
- **Use output subdirectory**: **COMPLIANT** ✓
- Output directory created and accessible in container
### Findings & Issues
- **Minor Issue**: Hadolint/shellcheck not integrated as automatic QA gate during build process, only available in validation script
- **No Critical Issues Found**: All primary requirements met
### Compliance Status
**Overall Compliance**: 95% - All critical requirements met, with minor process improvement opportunity for QA automation
### Recommendations
- Integrate hadolint/shellcheck validation into the build process for automatic QA gate
- Consider adding automated tests to validate that installed tools function correctly

47
Toolbox/docs/examples/joplin-note-sample.md Normal file
View File

@@ -0,0 +1,47 @@
# Meeting Notes: Documentation Toolchain Implementation
## Date: 2025-11-05
## Attendees: Charles Wyble, Jane Smith, John Doe
## Topic: Documentation Toolchain Setup
### Agenda
1. Review current documentation challenges
2. Discuss proposed toolchain solutions
3. Plan implementation timeline
### Current Challenges
- Inconsistent documentation formats across projects
- Lack of automated generation tools
- Poor integration with CI/CD pipelines
- Difficult to maintain multiple document versions
### Proposed Solutions
- Implement standardized documentation toolchain using pandoc, mdbook, and typst
- Containerize all tools for consistent environments
- Integrate with existing CI/CD systems
- Create templates for common document types
### Toolchain Decisions
- **Primary Format**: Markdown for source documents
- **Conversion Tools**:
- pandoc - for general conversions (Markdown to PDF/HTML/Docx)
- mdbook - for book-style documentation
- typst - for academic-style documents
- quarto - for data-driven documents
- **Styling**: LaTeX templates for PDF output
### Implementation Timeline
- **Week 1**: Environment setup with Docker
- **Week 2**: Template development
- **Week 3**: Integration with CI/CD
- **Week 4**: Testing and validation
- **Week 5**: Deployment and documentation
### Action Items
- [ ] Jane: Research pandoc LaTeX templates
- [ ] John: Create Dockerfile for toolchain
- [ ] Charles: Define security requirements
- [ ] All: Review and test prototype by EOW
### Next Meeting
Date: 2025-11-12, 14:00 UTC

38
Toolbox/docs/examples/mdbook-sample/src/SUMMARY.md Normal file
View File

@@ -0,0 +1,38 @@
# The Example Book
This is a sample book to demonstrate mdbook functionality.
## Chapter 1: Introduction
Welcome to this example book. This demonstrates the capabilities of mdbook for generating static documentation sites.
### Features of mdbook
- Write in Markdown
- Automatically generated table of contents
- Syntax highlighting for code blocks
- Cross-references between chapters
- Support for themes and custom CSS
```rust
fn main() {
println!("Hello, mdbook!");
}
```
## Chapter 2: Advanced Features
Mdbook supports several advanced features that enhance documentation:
- Internal link: [Introduction](./ch1.md)
- External link: [Rust Homepage](https://www.rust-lang.org)
- Images and diagrams
- Math formulas using KaTeX
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$
### Summary
This example demonstrates mdbook's core functionality. In a real project, you would have multiple chapters with detailed content.

38
Toolbox/docs/examples/mdbook-sample/summary.md Normal file
View File

@@ -0,0 +1,38 @@
# Example Book
This is a sample book to demonstrate mdbook functionality.
## Chapter 1: Introduction
Welcome to this example book. This demonstrates the capabilities of mdbook for generating static documentation sites.
### Features of mdbook
- Write in Markdown
- Automatically generated table of contents
- Syntax highlighting for code blocks
- Cross-references between chapters
- Support for themes and custom CSS
```rust
fn main() {
println!("Hello, mdbook!");
}
```
## Chapter 2: Advanced Features
Mdbook supports several advanced features that enhance documentation:
- Internal link: [Introduction](./ch1.md)
- External link: [Rust Homepage](https://www.rust-lang.org)
- Images and diagrams
- Math formulas using KaTeX
$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$
### Summary
This example demonstrates mdbook's core functionality. In a real project, you would have multiple chapters with detailed content.

70
Toolbox/docs/examples/project-plan.md Normal file
View File

@@ -0,0 +1,70 @@
# Project Plan: Documentation Toolchain
## Overview
This document outlines the plan for implementing a comprehensive documentation toolchain for the TSYS Development Stack.
## Timeline
- **Start Date:** 2025-11-15
- **Estimated Completion:** 2025-12-15
- **Review Date:** 2025-11-30
## Stakeholders
- **Project Lead:** Charles Wyble
- **Engineering Team:** DevOps Engineers
- **Quality Assurance:** Documentation Team
- **End Users:** All TSYS Developers
## Objectives
1. Implement a standardized documentation workflow
2. Integrate multiple documentation formats (Markdown, LaTeX, Typst)
3. Enable automated document generation
4. Provide CI/CD integration for documentation
## Work Packages
### WP1: Environment Setup (Week 1)
- Set up development environment
- Install documentation tools (pandoc, mdbook, typst, etc.)
- Configure build scripts
### WP2: Template Development (Week 2)
- Create document templates
- Develop style guides
- Standardize formatting
### WP3: Integration (Week 3)
- Integrate tools with existing systems
- Set up CI/CD pipeline
- Create documentation workflows
### WP4: Testing & Validation (Week 4)
- Test all document generation workflows
- Validate output quality
- Perform security scanning
### WP5: Deployment (Week 5)
- Deploy to production environments
- Provide user training
- Document procedures
## Deliverables
- Containerized documentation environment
- Automated build scripts
- Documentation templates
- User guides and tutorials
## Resources Required
- Development time: 10 person-weeks
- Infrastructure: Docker-enabled CI/CD system
- Tools: pandoc, mdbook, typst, quarto, and related libraries
## Success Criteria
- All documentation types generate correctly
- Integration with existing CI/CD systems
- 100% security scan compliance
- Performance benchmarks met
## Risks
- Dependency conflicts between tools
- Licensing issues with LaTeX packages
- Performance degradation with complex documents

42
Toolbox/docs/examples/resume-sample.md Normal file
View File

@@ -0,0 +1,42 @@
# John Doe - Software Engineer
## Contact Information
- Email: john.doe@example.com
- Phone: (555) 123-4567
- LinkedIn: linkedin.com/in/johndoe
- GitHub: github.com/johndoe
## Professional Summary
Experienced software engineer with 8+ years of expertise in developing scalable web applications and cloud infrastructure. Specialized in full-stack development with a focus on modern JavaScript frameworks and cloud technologies.
## Skills
- Languages: JavaScript, TypeScript, Python, Java, Go
- Frontend: React, Vue, Angular, HTML5, CSS3, SASS
- Backend: Node.js, Express, Django, Spring Boot
- Databases: PostgreSQL, MongoDB, Redis
- Cloud: AWS, Docker, Kubernetes, CI/CD
## Experience
### Senior Software Engineer | TechCorp | 2020 - Present
- Led development of a microservices architecture serving 1M+ users
- Reduced application load time by 40% through performance optimization
- Mentored 5 junior developers and conducted code reviews
### Software Engineer | StartupXYZ | 2018 - 2020
- Developed and maintained customer-facing web applications
- Implemented CI/CD pipeline reducing deployment time by 60%
- Collaborated with design team to improve UI/UX
### Junior Developer | ABC Solutions | 2016 - 2018
- Built and maintained internal tools and dashboards
- Participated in agile development process
- Assisted in troubleshooting production issues
## Education
**Bachelor of Science in Computer Science**
University of Technology | 2012 - 2016
## Certifications
- AWS Certified Solutions Architect
- Certified Kubernetes Administrator

100
Toolbox/docs/examples/resume-style.tex Normal file
View File

@@ -0,0 +1,100 @@
\documentclass[11pt,letterpaper]{article}
\usepackage[margin=1in]{geometry}
\usepackage{titlesec}
\usepackage{enumitem}
\usepackage[dvipsnames]{xcolor}
\usepackage{fontspec}
\usepackage{hyperref}
% Define colors
\definecolor{primaryColor}{RGB}{0, 43, 54}
\definecolor{secondaryColor}{RGB}{147, 161, 161}
% Set main font
\setmainfont{Carlito}
% Remove page numbering
\pagestyle{empty}
% Format section titles
\titleformat{\section}
{\large\bfseries\color{primaryColor}}
{}
{0em}
{\underline}
\titlespacing{\section}{0pt}{1.5ex}{0.5ex}
% Format subsection titles
\titleformat{\subsection}
{\normalsize\bfseries}
{}
{0em}
{}
\titlespacing{\subsection}{0pt}{1ex}{0.25ex}
% Set link colors
\hypersetup{
colorlinks=true,
linkcolor=secondaryColor,
urlcolor=secondaryColor
}
\begin{document}
% Header
\begin{center}
{\LARGE\bfseries\color{primaryColor} John Doe} \\ \vspace{0.2cm}
{\large Software Engineer} \\ \vspace{0.2cm}
\color{secondaryColor}
john.doe@example.com | (555) 123-4567 | linkedin.com/in/johndoe | github.com/johndoe
\end{center}
\vspace{0.3cm}
% Summary section
\section{Professional Summary}
\color{black}
Experienced software engineer with 8+ years of expertise in developing scalable web applications and cloud infrastructure. Specialized in full-stack development with a focus on modern JavaScript frameworks and cloud technologies.
\section{Skills}
\begin{itemize}[leftmargin=0.5cm, itemsep=0pt]
\item \textbf{Languages:} JavaScript, TypeScript, Python, Java, Go
\item \textbf{Frontend:} React, Vue, Angular, HTML5, CSS3, SASS
\item \textbf{Backend:} Node.js, Express, Django, Spring Boot
\item \textbf{Databases:} PostgreSQL, MongoDB, Redis
\item \textbf{Cloud:} AWS, Docker, Kubernetes, CI/CD
\end{itemize}
\section{Experience}
\subsection{Senior Software Engineer | TechCorp | 2020 - Present}
\begin{itemize}[leftmargin=0.5cm, itemsep=0pt]
\item Led development of a microservices architecture serving 1M+ users
\item Reduced application load time by 40\% through performance optimization
\item Mentored 5 junior developers and conducted code reviews
\end{itemize}
\subsection{Software Engineer | StartupXYZ | 2018 - 2020}
\begin{itemize}[leftmargin=0.5cm, itemsep=0pt]
\item Developed and maintained customer-facing web applications
\item Implemented CI/CD pipeline reducing deployment time by 60\%
\item Collaborated with design team to improve UI/UX
\end{itemize}
\subsection{Junior Developer | ABC Solutions | 2016 - 2018}
\begin{itemize}[leftmargin=0.5cm, itemsep=0pt]
\item Built and maintained internal tools and dashboards
\item Participated in agile development process
\item Assisted in troubleshooting production issues
\end{itemize}
\section{Education}
\textbf{Bachelor of Science in Computer Science} \\
University of Technology | 2012 - 2016
\section{Certifications}
\begin{itemize}[leftmargin=0.5cm, itemsep=0pt]
\item AWS Certified Solutions Architect
\item Certified Kubernetes Administrator
\end{itemize}
\end{document}

44
Toolbox/docs/examples/sample-bibliography.bib Normal file
View File

@@ -0,0 +1,44 @@
% Sample bibliography file for BibTool testing
@article{example2023,
title={An Example Article for BibTool},
author={Smith, John and Doe, Jane},
journal={Journal of Examples},
volume={1},
number={1},
pages={1--10},
year={2023},
publisher={Example Publisher},
doi={10.1234/example2023}
}
@book{another2023,
title={Another Example Book for BibTool},
author={Brown, Alice},
year={2023},
publisher={Example Academic Press},
address={New York},
isbn={978-1234567890}
}
@inproceedings{third2023,
title={A Conference Paper Example for BibTool},
author={Johnson, Bob and Williams, Carol},
booktitle={Proceedings of the International Conference on Examples},
pages={123--130},
year={2023},
organization={Example Organization}
}
% This is a duplicate entry to test BibTool's duplicate detection
@article{example2023_duplicate,
title={An Example Article for BibTool},
author={Smith, John and Doe, Jane},
journal={Journal of Examples},
volume={1},
number={1},
pages={1--10},
year={2023},
publisher={Example Publisher},
doi={10.1234/example2023}
}

10
Toolbox/docs/examples/sample-book/book.toml Normal file
View File

@@ -0,0 +1,10 @@
[book]
authors = ["TSYS Group"]
language = "en"
multilingual = false
src = "src"
title = "Sample mdBook Project"
[output.html]
git-repository-url = "https://github.com/tsysdevstack/toolbox"
edit-url-template = "https://github.com/tsysdevstack/toolbox/edit/main/{path}"

6
Toolbox/docs/examples/sample-book/src/SUMMARY.md Normal file
View File

@@ -0,0 +1,6 @@
# Summary
[Introduction](./chapters/intro.md)
[Getting Started](./chapters/getting-started.md)
[Advanced Features](./chapters/advanced.md)
[Conclusion](./chapters/conclusion.md)

55
Toolbox/docs/examples/sample-book/src/chapters/advanced.md Normal file
View File

@@ -0,0 +1,55 @@
# Advanced Features
This chapter covers more advanced features of mdBook that can enhance your documentation.
## Adding Custom CSS
You can customize the look of your book by adding CSS files to a theme directory:
```
mybook/
├── book.toml
└── src/
├── SUMMARY.md
└── ...
└── theme/
└── css/
└── custom.css
```
## Including Files
Use the `{{#include}}` syntax to include external files:
```markdown
{{#include ../../../path/to/file.rs}}
```
## Adding Math
Mathematical formulas are supported using KaTeX:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
Inline math: $E = mc^2$
## Admonitions
Special blocks for notes, warnings, etc.:
> Note: This is a note admonition.
> Warning: This is a warning admonition.
> Tip: This is a tip admonition.
## Adding Interactive Elements
You can include HTML directly in your markdown:
<details>
<summary>Click to expand</summary>
Hidden content goes here.
</details>

27
Toolbox/docs/examples/sample-book/src/chapters/conclusion.md Normal file
View File

@@ -0,0 +1,27 @@
# Conclusion
This concludes our sample mdBook project. You now know the basics of creating documentation with mdBook.
## What We've Covered
- Setting up an mdBook project
- Creating chapters with markdown
- Using advanced features like math and admonitions
- Building and serving your book
## Next Steps
Now that you understand the basics, you can:
1. Create your own documentation project
2. Customize the theme and styling
3. Add more complex content with interactive elements
4. Deploy your book to a web server
## Additional Resources
- [Official mdBook documentation](https://rust-lang.github.io/mdBook/)
- [Markdown guide](https://www.markdownguide.org/)
- [TSYS Documentation & Diagrams container](https://github.com/tsysdevstack/toolbox)
Thank you for exploring the capabilities of mdBook with the TSYS Documentation & Diagrams container!

47
Toolbox/docs/examples/sample-book/src/chapters/getting-started.md Normal file
View File

@@ -0,0 +1,47 @@
# Getting Started
This chapter will guide you through the basics of creating content with mdBook.
## Creating Your First Chapter
To create a new chapter:
1. Create a markdown file in the `src` directory
2. Add an entry in `SUMMARY.md` to include it in the navigation
3. Run `mdbook build` to generate the HTML
## Basic Markdown Syntax
You can use standard markdown syntax in your chapters:
```markdown
# Heading 1
## Heading 2
### Heading 3
- List item 1
- List item 2
- List item 3
[Link text](path/to/page.md)
![Image alt text](path/to/image.jpg)
```
## Code Blocks
Code blocks get syntax highlighting:
```rust
fn main() {
println!("Hello, world!");
}
```
```javascript
console.log("Hello, JavaScript!");
```
```python
print("Hello, Python!")
```

15
Toolbox/docs/examples/sample-book/src/chapters/intro.md Normal file
View File

@@ -0,0 +1,15 @@
# Introduction
Welcome to the Sample mdBook Project! This book demonstrates the capabilities of mdBook for creating documentation.
## What is mdBook?
mdBook is a utility to create books from markdown files. It is similar to GitBook but written in Rust.
## Features
- Write books in markdown
- Create a book with multiple chapters
- Automatically generated table of contents
- Syntax highlighting for code blocks
- Responsive design for mobile devices

27
Toolbox/docs/examples/sample-diagram.txt Normal file
View File

@@ -0,0 +1,27 @@
# Sample diagram for Kroki
graph TD
A[Documentation Tools] --> B[Pandoc]
A --> C[mdBook]
A --> D[Typst]
A --> E[Marp]
A --> F[Quarto]
B --> G[PDF Output]
B --> H[DOCX Output]
B --> I[HTML Output]
C --> J[Book Generation]
D --> K[Typesetting]
E --> L[Presentations]
F --> M[Scientific Reports]
G --> N[Print]
H --> O[Word Processing]
I --> P[Web Publishing]
J --> Q[Documentation Sites]
K --> R[Academic Papers]
L --> S[Slides]
M --> T[Research Papers]
style A fill:#f9f,stroke:#333,stroke-width:2px

62
Toolbox/docs/examples/sample-markdown.md Normal file
View File

@@ -0,0 +1,62 @@
# Sample Document for Pandoc Testing
This is a sample document to test the pandoc functionality in the TSYS Documentation & Diagrams container.
## Heading 2
This document contains various elements to test pandoc's conversion capabilities:
- Bullet list item 1
- Bullet list item 2
- Nested item
- Bullet list item 3
### Heading 3
1. Numbered list item 1
2. Numbered list item 2
1. Nested numbered item
3. Numbered list item 3
> This is a blockquote to test pandoc's handling of quoted text.
Here is some `inline code` and a code block:
```python
def hello_world():
print("Hello, world!")
return True
```
**Bold text** and *italic text* should render correctly.
## Table Example
| Column 1 | Column 2 | Column 3 |
| :--- | :--- | :--- |
| Left-aligned | Left-aligned | Left-aligned |
| Item 1 | Value 1 | Status 1 |
| Item 2 | Value 2 | Status 2 |
| Item 3 | Value 3 | Status 3 |
## Link and Image
Here is a [link to pandoc's website](https://pandoc.org).
![Placeholder image](https://placehold.co/150 "Placeholder")
## Mathematical Formula
Here is an inline equation: $E = mc^2$
And here is a block equation:
$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
## Citations
This statement needs a citation [@example2023].
This one too [@another2023; @third2023].
# References

106
Toolbox/docs/examples/sample-presentation.md Normal file
View File

@@ -0,0 +1,106 @@
---
marp: true
theme: uncover
paginate: true
---
# TSYS Documentation & Diagrams
## A Marp Presentation Sample
---
## What's in this Container?
- **Pandoc** - Universal document converter
- **mdBook** - Book generation from Markdown
- **Typst** - Modern typesetting system
- **Marp** - Markdown presentation creator
- **Quarto** - Scientific publishing system
- **And more!**
---
## Key Features
- Runs as non-root user
- Uses `mise` for runtime management
- Version-pinned packages
- Multi-platform support
- Security-first design
---
## Document Conversion
Convert documents between formats easily:
```bash
pandoc input.md -o output.pdf
```
Or with custom styling:
```bash
pandoc input.md --reference-doc=template.docx -o output.docx
```
---
## Multi-format Publishing
Create documents in multiple formats simultaneously:
- PDF for print
- HTML for web
- DOCX for word processing
- EPUB for e-readers
---
## Code Example
Highlighting code in presentations:
```javascript
function helloWorld() {
console.log("Hello, world!");
return true;
}
```
---
## Math Support
Equations in presentations:
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
---
## Diagrams
Create diagrams with Kroki:
```mermaid
graph TD
A[Document] --> B{Format}
B --> C[PDF]
B --> D[HTML]
B --> E[DOCX]
```
---
## Thank You!
For more information, check out the documentation:
- README.md
- USAGE.md
- Troubleshooting Guide
Questions?

97
Toolbox/docs/examples/sample-report.qmd Normal file
View File

@@ -0,0 +1,97 @@
---
title: "TSYS Documentation & Diagrams Sample Report"
author: "TSYS Group"
date: "2025-11-07"
format:
html:
theme: cosmo
toc: true
pdf:
documentclass: article
docx:
reference-doc: template.docx
jupyter: python3
---
## Overview
This report demonstrates the capabilities of Quarto for creating reproducible scientific reports. Quarto is a powerful open-source scientific and technical publishing system that supports multiple input formats, numerous output formats, and integrates with R, Python, Julia, and Observable.
## Data Analysis with Python
We can embed code directly in the document:
```{python}
#| echo: true
import matplotlib.pyplot as plt
import numpy as np
# Generate sample data
x = np.linspace(0, 10, 100)
y = np.sin(x)
# Create plot
plt.figure(figsize=(10, 6))
plt.plot(x, y, label='sin(x)')
plt.title('Sine Wave')
plt.xlabel('x')
plt.ylabel('sin(x)')
plt.legend()
plt.grid(True)
plt.show()
```
## Mathematical Formulas
Quarto supports both inline math $E = mc^2$ and display math:
$$\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}$$
## Citations
We can reference academic works in our document. For example, research has shown the importance of reproducible research [@peng2009].
## Tables
| Tool | Purpose | Key Feature |
|------|---------|-------------|
| Pandoc | Document conversion | Universal converter |
| mdBook | Book generation | Markdown-based |
| Typst | Typesetting | Fast and modern |
| Marp | Presentations | Markdown-based |
| Quarto | Scientific publishing | Multi-language support |
## Diagrams
With integrated Kroki support, we can include diagrams:
```mermaid
graph TD
A[Input Document] --> B{Quarto}
B --> C[HTML Output]
B --> D[PDF Output]
B --> E[DOCX Output]
B --> F[Beamer Slides]
```
## Code Execution
Quarto allows executing code in multiple languages:
```{python}
#| echo: true
import pandas as pd
# Create sample data frame
data = {'Name': ['Alice', 'Bob', 'Charlie'],
'Age': [25, 30, 35],
'City': ['New York', 'London', 'Tokyo']}
df = pd.DataFrame(data)
print(df)
```
## Conclusion
This sample demonstrates Quarto's powerful features for creating reproducible, multi-format documents that combine narrative text, code, and output. The TSYS Documentation & Diagrams container provides all the necessary tools for comprehensive document production workflows.
## References

66
Toolbox/docs/examples/sample-typst.typ Normal file
View File

@@ -0,0 +1,66 @@
// Sample Typst document to demonstrate typesetting capabilities
#set page(width: 12cm, height: 16cm, margin: 2cm)
#set text(family: "Linux Libertine", size: 11pt)
= TSYS Documentation & Diagrams
A Typst Sample Document
#lorem(30)
== Introduction
#lorem(50)
== Features of Typst
Typst offers many advantages for document creation:
- #h(0.3em) *Fast and Modern* - Built for efficiency and speed
- #h(0.3em) *Markup-based* - Clean, semantic syntax
- #h(0.3em) *Powerful Typesetting* - Professional output quality
#lorem(40)
== Code Example
Here's how to write code in Typst:
```
#let greet(name) = [
Hello, #name!
]
#greet("World")
```
== Mathematical Expressions
Typst has excellent support for mathematical expressions:
- Inline math: #math.equation( sum_(i=0)^n i^2 = (n(n+1)(2n+1))/6 )
- Block equations:
$
f(x) = int_-∞^∞ hat f(xi),e^2 pi i xi x dxi
$
== Table Example
#table(
columns: 3,
[Column 1], [Column 2], [Column 3],
[Item 1], [Value 1], [Status 1],
[Item 2], [Value 2], [Status 2],
[Item 3], [Value 3], [Status 3],
)
== Conclusion
#lorem(40)
= References
#let reference(title, author, year) = [
#h(1.5em) #author (#year). #title.
]
#reference("Typst: A New Markup-Based Typesetting System", "Typst Team", 2023)

294
Toolbox/docs/examples/workflow-demo.sh Executable file
View File

@@ -0,0 +1,294 @@
#!/usr/bin/env bash
# workflow-demo.sh - Demonstration script for common documentation workflows
# Shows how to use the container with various example files
set -euo pipefail
# Configuration
IMAGE_NAME="tsysdevstack-toolboxes-docs"
EXAMPLES_DIR="examples"
OUTPUT_DIR="output/demo"
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m' # No Color
# Function to print colored output
print_status() {
echo -e "${BLUE}[INFO]${NC} $1"
}
print_success() {
echo -e "${GREEN}[SUCCESS]${NC} $1"
}
print_warning() {
echo -e "${YELLOW}[WARNING]${NC} $1"
}
print_error() {
echo -e "${RED}[ERROR]${NC} $1"
}
# Function to check if container exists
check_container() {
if ! docker images | grep -q "$IMAGE_NAME"; then
print_error "Container image '$IMAGE_NAME' not found. Please build it first:"
echo " ./output/build.sh"
exit 1
fi
}
# Function to create output directory
setup_output() {
mkdir -p "$OUTPUT_DIR"
print_status "Created output directory: $OUTPUT_DIR"
}
# Function to demonstrate resume generation
demo_resume() {
print_status "📄 Demonstrating resume generation..."
if docker run --rm \
-v "$(pwd)/$EXAMPLES_DIR:/home/tsysdevstack/examples:ro" \
-v "$(pwd)/$OUTPUT_DIR:/home/tsysdevstack/output" \
"$IMAGE_NAME" \
pandoc /home/tsysdevstack/examples/resume-sample.md \
-o /home/tsysdevstack/output/resume.pdf \
--pdf-engine=xelatex; then
print_success "Resume generated: $OUTPUT_DIR/resume.pdf"
else
print_error "Failed to generate resume"
fi
}
# Function to demonstrate project documentation
demo_project_docs() {
print_status "📚 Demonstrating project documentation..."
if docker run --rm \
-v "$(pwd)/$EXAMPLES_DIR:/home/tsysdevstack/examples:ro" \
-v "$(pwd)/$OUTPUT_DIR:/home/tsysdevstack/output" \
"$IMAGE_NAME" \
pandoc /home/tsysdevstack/examples/project-plan.md \
-o /home/tsysdevstack/output/project-plan.html \
--standalone; then
print_success "Project documentation generated: $OUTPUT_DIR/project-plan.html"
else
print_error "Failed to generate project documentation"
fi
}
# Function to demonstrate mdbook
demo_mdbook() {
print_status "📖 Demonstrating mdbook generation..."
if docker run --rm \
-v "$(pwd)/$EXAMPLES_DIR:/home/tsysdevstack/examples:ro" \
-v "$(pwd)/$OUTPUT_DIR:/home/tsysdevstack/output" \
"$IMAGE_NAME" \
bash -c "cd /home/tsysdevstack/examples/mdbook-sample && mdbook build -d /home/tsysdevstack/output/mdbook-demo"; then
print_success "mdbook generated: $OUTPUT_DIR/mdbook-demo/"
else
print_error "Failed to generate mdbook"
fi
}
# Function to demonstrate typst
demo_typst() {
print_status "🎨 Demonstrating typst compilation..."
if docker run --rm \
-v "$(pwd)/$EXAMPLES_DIR:/home/tsysdevstack/examples:ro" \
-v "$(pwd)/$OUTPUT_DIR:/home/tsysdevstack/output" \
"$IMAGE_NAME" \
typst compile /home/tsysdevstack/examples/sample-typst.typ \
/home/tsysdevstack/output/typst-demo.pdf; then
print_success "Typst document generated: $OUTPUT_DIR/typst-demo.pdf"
else
print_error "Failed to compile typst document"
fi
}
# Function to demonstrate presentation
demo_presentation() {
print_status "🎯 Demonstrating presentation generation..."
if docker run --rm \
-v "$(pwd)/$EXAMPLES_DIR:/home/tsysdevstack/examples:ro" \
-v "$(pwd)/$OUTPUT_DIR:/home/tsysdevstack/output" \
"$IMAGE_NAME" \
bash -c "npx --package @marp-team/marp-cli marp /home/tsysdevstack/examples/sample-presentation.md -o /home/tsysdevstack/output/presentation.pdf"; then
print_success "Presentation generated: $OUTPUT_DIR/presentation.pdf"
else
print_error "Failed to generate presentation"
fi
}
# Function to demonstrate quarto
demo_quarto() {
print_status "🔬 Demonstrating quarto rendering..."
if docker run --rm \
-v "$(pwd)/$EXAMPLES_DIR:/home/tsysdevstack/examples:ro" \
-v "$(pwd)/$OUTPUT_DIR:/home/tsysdevstack/output" \
"$IMAGE_NAME" \
quarto render /home/tsysdevstack/examples/sample-report.qmd \
--output /home/tsysdevstack/output/quarto-report.html; then
print_success "Quarto report generated: $OUTPUT_DIR/quarto-report.html"
else
print_error "Failed to render quarto report"
fi
}
# Function to demonstrate Joplin note conversion
demo_joplin() {
print_status "📝 Demonstrating Joplin note conversion..."
if docker run --rm \
-v "$(pwd)/$EXAMPLES_DIR:/home/tsysdevstack/examples:ro" \
-v "$(pwd)/$OUTPUT_DIR:/home/tsysdevstack/output" \
"$IMAGE_NAME" \
pandoc /home/tsysdevstack/examples/joplin-note-sample.md \
-o /home/tsysdevstack/output/joplin-note.pdf \
--pdf-engine=xelatex; then
print_success "Joplin note converted: $OUTPUT_DIR/joplin-note.pdf"
else
print_error "Failed to convert Joplin note"
fi
}
# Function to demonstrate bibliography management
demo_bibliography() {
print_status "📚 Demonstrating bibliography management..."
if docker run --rm \
-v "$(pwd)/$EXAMPLES_DIR:/home/tsysdevstack/examples:ro" \
-v "$(pwd)/$OUTPUT_DIR:/home/tsysdevstack/output" \
"$IMAGE_NAME" \
bibtool -s /home/tsysdevstack/examples/sample-bibliography.bib > "$OUTPUT_DIR/cleaned-bibliography.bib"; then
print_success "Bibliography processed: $OUTPUT_DIR/cleaned-bibliography.bib"
else
print_error "Failed to process bibliography"
fi
}
# Function to show generated files
show_results() {
print_status "📋 Generated files:"
if [[ -d "$OUTPUT_DIR" ]]; then
ls -la "$OUTPUT_DIR/" || true
fi
}
# Function to print usage
print_usage() {
echo "Usage: $0 [OPTIONS] [WORKFLOW...]"
echo ""
echo "Demonstration script for documentation workflows."
echo ""
echo "Options:"
echo " --help, -h Show this help message"
echo " --all Run all demonstrations (default)"
echo " --clean Clean output directory before running"
echo ""
echo "Available workflows:"
echo " resume Generate resume from markdown"
echo " project Generate project documentation"
echo " mdbook Generate mdbook documentation"
echo " typst Compile typst document"
echo " presentation Generate presentation"
echo " quarto Render quarto report"
echo " joplin Convert Joplin note"
echo " bibliography Process bibliography"
echo ""
echo "Examples:"
echo " $0 --all # Run all demonstrations"
echo " $0 resume presentation # Run specific workflows"
echo " $0 --clean mdbook # Clean and run mdbook demo"
}
# Main execution
main() {
local run_all=true
local clean_output=false
local workflows=()
# Parse command line arguments
while [[ $# -gt 0 ]]; do
case $1 in
--help|-h)
print_usage
exit 0
;;
--all)
run_all=true
shift
;;
--clean)
clean_output=true
shift
;;
resume|project|mdbook|typst|presentation|quarto|joplin|bibliography)
run_all=false
workflows+=("$1")
shift
;;
*)
print_error "Unknown option: $1"
print_usage
exit 1
;;
esac
done
print_status "🚀 Starting documentation workflow demonstrations..."
# Check prerequisites
check_container
# Setup
if [[ "$clean_output" == true ]]; then
rm -rf "$OUTPUT_DIR"
print_status "Cleaned output directory"
fi
setup_output
# Run workflows
if [[ "$run_all" == true ]]; then
demo_resume
demo_project_docs
demo_mdbook
demo_typst
demo_presentation
demo_quarto
demo_joplin
demo_bibliography
else
for workflow in "${workflows[@]}"; do
case $workflow in
resume) demo_resume ;;
project) demo_project_docs ;;
mdbook) demo_mdbook ;;
typst) demo_typst ;;
presentation) demo_presentation ;;
quarto) demo_quarto ;;
joplin) demo_joplin ;;
bibliography) demo_bibliography ;;
esac
done
fi
# Show results
show_results
print_success "✅ All demonstrations completed successfully!"
print_status "Check the '$OUTPUT_DIR' directory for generated files."
}
# Run main function with all arguments
main "$@"