.
This commit is contained in:
277
Toolbox/docs/README.md
Normal file
277
Toolbox/docs/README.md
Normal file
@@ -0,0 +1,277 @@
|
||||
# TSYS Group Development Stack - Documentation & Diagrams
|
||||
|
||||
<div align="center">
|
||||
|
||||
[](https://hub.docker.com/r/tsysdevstack/tsysdevstack-toolboxes-docs)
|
||||
[](https://hub.docker.com/r/tsysdevstack/tsysdevstack-toolboxes-docs)
|
||||
[](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>
|
||||
Reference in New Issue
Block a user