add docker compilation
This commit is contained in:
parent
b7f970e42e
commit
219ebf81bf
114
Makefile
114
Makefile
@ -45,12 +45,32 @@ YELLOW = \033[1;33m
|
||||
BLUE = \033[0;34m
|
||||
NC = \033[0m # No Color
|
||||
|
||||
# Docker Compose command detection
|
||||
# Support both docker-compose (standalone) and docker compose (plugin)
|
||||
DOCKER_COMPOSE := $(shell command -v docker-compose 2> /dev/null)
|
||||
ifdef DOCKER_COMPOSE
|
||||
DOCKER_COMPOSE_CMD = docker-compose
|
||||
DOCKER_COMPOSE_TYPE = standalone
|
||||
else
|
||||
DOCKER_COMPOSE_CMD = docker compose
|
||||
DOCKER_COMPOSE_TYPE = plugin
|
||||
endif
|
||||
|
||||
# Docker availability check
|
||||
DOCKER_AVAILABLE := $(shell command -v docker 2> /dev/null)
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Main Targets
|
||||
# ------------------------------------------------------------------------------
|
||||
# Default target: Use Docker for compilation if available
|
||||
.PHONY: all
|
||||
all: compile view
|
||||
@echo -e "$(GREEN)✓ Document built and opened successfully$(NC)"
|
||||
all: docker-build
|
||||
@echo -e "$(GREEN)✓ Document built successfully using Docker$(NC)"
|
||||
|
||||
# Alternative: Local build without Docker
|
||||
.PHONY: local
|
||||
local: compile view
|
||||
@echo -e "$(GREEN)✓ Document built and opened successfully (local)$(NC)"
|
||||
|
||||
.PHONY: compile
|
||||
compile:
|
||||
@ -76,6 +96,79 @@ view:
|
||||
exit 1; \
|
||||
fi
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Docker Targets
|
||||
# ------------------------------------------------------------------------------
|
||||
.PHONY: docker-info
|
||||
docker-info:
|
||||
@echo -e "$(BLUE)=== Docker Configuration ===$(NC)"
|
||||
@if command -v docker >/dev/null 2>&1; then \
|
||||
echo -e "$(GREEN)✓ Docker:$(NC) $$(docker --version | cut -d' ' -f3 | tr -d ',')"; \
|
||||
else \
|
||||
echo -e "$(RED)✗ Docker:$(NC) Not found"; \
|
||||
fi
|
||||
@echo -e "$(GREEN)✓ Docker Compose:$(NC) $(DOCKER_COMPOSE_CMD) ($(DOCKER_COMPOSE_TYPE))"
|
||||
@if command -v docker >/dev/null 2>&1 && docker info >/dev/null 2>&1; then \
|
||||
echo -e "$(GREEN)✓ Docker Daemon:$(NC) Running"; \
|
||||
echo -e "$(GREEN)✓ Containers:$(NC) $$(docker ps -q | wc -l) running, $$(docker ps -aq | wc -l) total"; \
|
||||
echo -e "$(GREEN)✓ Images:$(NC) $$(docker images -q | wc -l) available"; \
|
||||
else \
|
||||
echo -e "$(YELLOW)⚠ Docker Daemon:$(NC) Not running or not accessible"; \
|
||||
fi
|
||||
@echo ""
|
||||
|
||||
.PHONY: check-docker
|
||||
check-docker:
|
||||
@command -v docker >/dev/null 2>&1 || { \
|
||||
echo -e "$(RED)✗ Docker is not installed or not in PATH$(NC)"; \
|
||||
echo -e "$(YELLOW) Please install Docker from https://docs.docker.com/get-docker/$(NC)"; \
|
||||
exit 1; \
|
||||
}
|
||||
@docker info >/dev/null 2>&1 || { \
|
||||
echo -e "$(RED)✗ Docker daemon is not running$(NC)"; \
|
||||
echo -e "$(YELLOW) Please start Docker Desktop or the Docker daemon$(NC)"; \
|
||||
exit 1; \
|
||||
}
|
||||
@echo -e "$(GREEN)✓ Docker is available$(NC)"
|
||||
@echo -e "$(YELLOW)→ Using Docker Compose command: $(DOCKER_COMPOSE_CMD)$(NC)"
|
||||
|
||||
.PHONY: docker-build
|
||||
docker-build: check-docker
|
||||
@echo -e "$(BLUE)=== Building LaTeX Document with Docker ===$(NC)"
|
||||
@echo -e "$(YELLOW)→ Starting Docker container...$(NC)"
|
||||
@$(DOCKER_COMPOSE_CMD) up --build || { \
|
||||
echo -e "$(RED)✗ Docker build failed$(NC)"; \
|
||||
echo -e "$(YELLOW) Try 'make docker-clean' and rebuild$(NC)"; \
|
||||
exit 1; \
|
||||
}
|
||||
@echo -e "$(GREEN)✓ Docker build completed$(NC)"
|
||||
@echo -e "$(GREEN)✓ PDF created: $(PDF_TARGET)$(NC)"
|
||||
|
||||
.PHONY: docker-build-cached
|
||||
docker-build-cached: check-docker
|
||||
@echo -e "$(BLUE)=== Building LaTeX Document with Docker (cached) ===$(NC)"
|
||||
@echo -e "$(YELLOW)→ Starting Docker container (using cache)...$(NC)"
|
||||
@$(DOCKER_COMPOSE_CMD) up || { \
|
||||
echo -e "$(RED)✗ Docker build failed$(NC)"; \
|
||||
echo -e "$(YELLOW) Try 'make docker-build' to rebuild the image$(NC)"; \
|
||||
exit 1; \
|
||||
}
|
||||
@echo -e "$(GREEN)✓ Docker build completed$(NC)"
|
||||
|
||||
.PHONY: docker-clean
|
||||
docker-clean: check-docker
|
||||
@echo -e "$(YELLOW)→ Removing Docker containers...$(NC)"
|
||||
@$(DOCKER_COMPOSE_CMD) down --remove-orphans || true
|
||||
@echo -e "$(GREEN)✓ Docker containers removed$(NC)"
|
||||
|
||||
.PHONY: docker-shell
|
||||
docker-shell: check-docker
|
||||
@echo -e "$(BLUE)→ Opening shell in Docker container...$(NC)"
|
||||
@$(DOCKER_COMPOSE_CMD) run --rm --entrypoint /bin/bash latex || { \
|
||||
echo -e "$(RED)✗ Failed to start Docker shell$(NC)"; \
|
||||
exit 1; \
|
||||
}
|
||||
|
||||
# ------------------------------------------------------------------------------
|
||||
# Clean Targets
|
||||
# ------------------------------------------------------------------------------
|
||||
@ -204,11 +297,20 @@ help:
|
||||
@echo -e "===============================================================================$(NC)"
|
||||
@echo ""
|
||||
@echo -e "$(GREEN)Main Targets:$(NC)"
|
||||
@echo " make - Build document and open PDF"
|
||||
@echo " make compile - Build the LaTeX document"
|
||||
@echo " make - Build document using Docker (default)"
|
||||
@echo " make local - Build document locally and open PDF"
|
||||
@echo " make compile - Build the LaTeX document (local)"
|
||||
@echo " make full - Clean and rebuild everything"
|
||||
@echo " make view - Open the PDF file"
|
||||
@echo ""
|
||||
@echo -e "$(GREEN)Docker Targets:$(NC)"
|
||||
@echo " make docker-info - Show Docker configuration and status"
|
||||
@echo " make check-docker - Check if Docker is available"
|
||||
@echo " make docker-build - Build with Docker (rebuild image)"
|
||||
@echo " make docker-build-cached - Build with Docker (use cached image)"
|
||||
@echo " make docker-shell - Open shell in Docker container"
|
||||
@echo " make docker-clean - Remove Docker containers"
|
||||
@echo ""
|
||||
@echo -e "$(GREEN)Chapter Management:$(NC)"
|
||||
@echo " make chapter NUM=02 NAME=methodology - Create a new chapter"
|
||||
@echo " make chapters - List all chapters"
|
||||
@ -237,5 +339,5 @@ help:
|
||||
@echo " make show-chapter NAME=01_introduction"
|
||||
@echo ""
|
||||
|
||||
# Default target
|
||||
.DEFAULT_GOAL := help
|
||||
# Default target - use Docker build
|
||||
.DEFAULT_GOAL := all
|
||||
|
||||
99
README.md
99
README.md
@ -25,15 +25,29 @@ The HSRTReport class is a customized LaTeX document class based on KOMA-Script's
|
||||
|
||||
- **Professional Typography**: Configured for optimal readability with proper font settings
|
||||
- **Automatic Title Page Generation**: Customizable title page with university branding
|
||||
- **Bibliography Management**: Integrated BibLaTeX support for citations
|
||||
- **Bibliography Management**: Integrated BibLaTeX support for APA-style citations
|
||||
- **Glossary Support**: Built-in glossary and acronym management
|
||||
- **Code Highlighting**: Syntax highlighting for source code listings
|
||||
- **Code Highlighting**: Syntax highlighting for multiple programming languages
|
||||
- **Word Count**: Automatic word counting functionality
|
||||
- **Cross-referencing**: Smart referencing with hyperref
|
||||
- **Advanced Page Break Control**: Intelligent section and listing page break management
|
||||
- **Docker Support**: Containerized build environment for consistent compilation
|
||||
- **Enhanced Spacing**: Optimized vertical spacing for sections and subsections
|
||||
- **Smart TOC Grouping**: Automatic chapter grouping in table of contents
|
||||
|
||||
## 🔧 Prerequisites
|
||||
|
||||
### Required Software
|
||||
### Option 1: Docker (Recommended)
|
||||
|
||||
- **Docker**: [Install Docker](https://docs.docker.com/get-docker/)
|
||||
- **Docker Compose**: Supports both variants:
|
||||
- `docker-compose` (standalone tool)
|
||||
- `docker compose` (Docker plugin, included with Docker Desktop)
|
||||
- The Makefile automatically detects which version is available
|
||||
|
||||
This is the easiest way to get started, as all LaTeX dependencies are handled automatically in a container.
|
||||
|
||||
### Option 2: Local Installation
|
||||
|
||||
- **XeLaTeX**: This template requires XeLaTeX for compilation (included in most TeX distributions)
|
||||
- **TeX Distribution**: One of the following:
|
||||
@ -41,6 +55,7 @@ The HSRTReport class is a customized LaTeX document class based on KOMA-Script's
|
||||
- [MiKTeX](https://miktex.org/) (Windows)
|
||||
- [MacTeX](https://www.tug.org/mactex/) (macOS)
|
||||
- **GNU make**: Automates compilation and cleaning tasks
|
||||
- **Inkscape**: For SVG to PDF conversion (optional, but needed for SVG graphics)
|
||||
|
||||
### Required LaTeX Packages
|
||||
|
||||
@ -103,6 +118,7 @@ SAT-WiSe-25-26/
|
||||
├── Main.bib # Bibliography database
|
||||
├── Makefile # Build automation
|
||||
├── .latexmkrc # Latexmk configuration
|
||||
├── docker-compose.yml # Docker configuration
|
||||
└── QUICKSTART.md # Quick start guide
|
||||
```
|
||||
|
||||
@ -232,23 +248,52 @@ Removes the chapter and creates a backup in `.chapter_backups/`.
|
||||
|
||||
## 🔨 Building the Document
|
||||
|
||||
### Using Make (Recommended)
|
||||
### Using Docker (Recommended - Default)
|
||||
|
||||
The template now uses Docker by default for consistent builds across all platforms. The Makefile automatically detects whether you have `docker-compose` (standalone) or `docker compose` (plugin) installed:
|
||||
|
||||
```bash
|
||||
# Full build with bibliography and glossary – open after
|
||||
# Show Docker configuration and which compose variant is used
|
||||
make docker-info
|
||||
|
||||
# Default build using Docker
|
||||
make
|
||||
|
||||
# Just build
|
||||
# Docker build with image rebuild (after Dockerfile changes)
|
||||
make docker-build
|
||||
|
||||
# Docker build using cached image (faster)
|
||||
make docker-build-cached
|
||||
|
||||
# Open shell in Docker container for debugging
|
||||
make docker-shell
|
||||
|
||||
# Clean Docker containers
|
||||
make docker-clean
|
||||
```
|
||||
|
||||
### Using Local Installation
|
||||
|
||||
If you have a local LaTeX installation:
|
||||
|
||||
```bash
|
||||
# Local build with automatic PDF viewing
|
||||
make local
|
||||
|
||||
# Just compile without opening
|
||||
make compile
|
||||
|
||||
# Clean auxiliary files
|
||||
make clean
|
||||
|
||||
# Full clean including output
|
||||
make distclean
|
||||
```
|
||||
|
||||
### Using latexmk
|
||||
### Using latexmk directly
|
||||
|
||||
```bash
|
||||
latexmk -xelatex -bibtex Main.tex
|
||||
latexmk -xelatex -shell-escape -bibtex Main.tex
|
||||
```
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
@ -258,15 +303,29 @@ latexmk -xelatex -bibtex Main.tex
|
||||
1. **"This class can only be used with XeLaTeX" error**
|
||||
- Solution: Ensure you're using XeLaTeX, not pdfLaTeX
|
||||
- Check your editor's compiler settings
|
||||
- Use Docker build (`make`) to avoid this issue
|
||||
|
||||
2. **Bibliography not appearing**
|
||||
- Run `biber Main` after the first XeLaTeX compilation
|
||||
- Check for errors in `Main.bib`
|
||||
- The Docker build handles this automatically
|
||||
|
||||
3. **Glossary entries not showing**
|
||||
- Run `makeglossaries Main` after adding new entries
|
||||
- Ensure entries are referenced in the document using `\gls{term}`
|
||||
|
||||
4. **Docker build not working**
|
||||
- Ensure Docker Desktop is running
|
||||
- Run `make docker-info` to check your Docker setup
|
||||
- Check that port is not blocked by firewall
|
||||
- Try `docker-compose build --no-cache` or `docker compose build --no-cache` for a fresh build
|
||||
- The Makefile supports both `docker-compose` and `docker compose` automatically
|
||||
|
||||
5. **SVG images not converting**
|
||||
- Inkscape is required for SVG support
|
||||
- Docker build includes Inkscape automatically
|
||||
- For local builds: Install Inkscape separately
|
||||
|
||||
## 📄 License
|
||||
|
||||
This template is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA 4.0).
|
||||
@ -290,4 +349,26 @@ For questions, issues, or suggestions:
|
||||
|
||||
---
|
||||
|
||||
*Last updated: October 2025*
|
||||
## 🆕 Recent Updates
|
||||
|
||||
### Version 2.0 (October 2024)
|
||||
- Added Docker support for containerized compilation
|
||||
- Implemented advanced page break control system
|
||||
- Enhanced section spacing (4.5ex before sections, 3.5ex before subsections)
|
||||
- Added smart TOC chapter grouping for short chapters
|
||||
- Updated header format with em-dash separator (e.g., "1 – Introduction")
|
||||
- Fixed page numbering (TOC now starts at page 1)
|
||||
- Added comprehensive bibliography with academic writing references
|
||||
- Improved listing and itemize environment protection from page breaks
|
||||
|
||||
### Key Configuration Changes
|
||||
- **Page Margins**: Unified 2cm on all sides
|
||||
- **Base Font Size**: 11pt
|
||||
- **Line Spacing**: 1.5x (`baselinestretch=1.5`)
|
||||
- **Paragraph Spacing**: 6pt
|
||||
- **Section Minimum Content**: 12 baseline skips (~2 paragraphs)
|
||||
- **Citation Style**: APA format via BibLaTeX
|
||||
|
||||
---
|
||||
|
||||
*Last updated: October 2024*
|
||||
|
||||
@ -1,14 +1,50 @@
|
||||
# ==============================================================================
|
||||
# Docker Compose Configuration for LaTeX Compilation
|
||||
# ==============================================================================
|
||||
# Description: This Docker Compose file sets up a containerized LaTeX build
|
||||
# environment with all necessary dependencies for compiling the
|
||||
# HSRTReport template documents.
|
||||
# Usage: docker-compose up (or make docker-build)
|
||||
# ==============================================================================
|
||||
|
||||
services:
|
||||
# ------------------------------------------------------------------------------
|
||||
# LaTeX Compilation Service
|
||||
# ------------------------------------------------------------------------------
|
||||
# This service provides a complete TeXLive environment for document compilation
|
||||
latex:
|
||||
# Base image: Full TeXLive distribution (latest version)
|
||||
# Note: The image line is commented out because we're using a custom build
|
||||
#image: texlive/texlive:latest
|
||||
|
||||
# Custom build configuration to add additional dependencies
|
||||
build:
|
||||
# Build context is the current directory
|
||||
context: .
|
||||
# Inline Dockerfile definition for additional packages
|
||||
dockerfile_inline: |
|
||||
# Start from the full TeXLive image (includes XeLaTeX, Biber, etc.)
|
||||
FROM texlive/texlive:latest
|
||||
|
||||
# Update package lists to ensure we get the latest versions
|
||||
RUN apt update -y
|
||||
|
||||
# Install Inkscape for SVG to PDF conversion
|
||||
# Required for processing SVG graphics in the document
|
||||
RUN apt install inkscape -y
|
||||
|
||||
# Volume mappings
|
||||
volumes:
|
||||
# Mount the entire project directory to /data in the container
|
||||
# This allows the container to access all project files and write outputs
|
||||
- ./:/data
|
||||
|
||||
# Working directory configuration
|
||||
# Previous project-specific path (kept for reference):
|
||||
# working_dir: /data/Projektbeschreibung-MKI-METI-Projekt
|
||||
# Current: Set to /data root for general use
|
||||
working_dir: /data
|
||||
|
||||
# Default command when container starts
|
||||
# Executes 'make compile' to build the LaTeX document
|
||||
entrypoint: ["make", "compile"]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user