How ethercod3/diploma_latex works
1. This repository is not an application runtime; it is a reproducible build system for a thesis package. The primary deliverable is a compiled LaTeX PDF, with supporting assets generated from Mermaid, Python-based diagram scripts, and DOCX title-page templates.
2. The central source-of-truth is the main LaTeX document Куприянов_И221_диплом.tex, backed by preamble/, appendix/, tables/, bibliography.bib, and fonts/. LaTeX is built with LuaLaTeX plus biblatex/biber, and the document can also pull in external code listings from a sibling code repository path.
3. Generated assets form a strict boundary around the LaTeX build: Mermaid diagrams are compiled from mermaid/*.mmd into PDFs under figures/, Python diagram scripts in python_diagrams/ also emit figures, and docx/*.docx are converted into титульник.pdf and задание.pdf in the repository root. The final LaTeX build consumes those generated PDFs/images rather than raw source formats.
4. Build orchestration is unified through Taskfile.yml and the tasks/ split. The high-level flow is sequential: generate DOCX PDFs, generate Mermaid diagrams, generate Python diagrams, then compile the thesis LaTeX. The same orchestration is exposed both locally and through Docker Compose profiles.
5. The Python scripts/ directory contains the operational layer for builds and utilities. It includes LaTeX builders, Mermaid compilation, PDF cropping, DOCX-to-PDF conversion, PDF diffing between commits, checksum updates, and a backup workflow. These scripts are the glue between source assets, external CLI tools, and the final artifacts.
6. Docker is used as an isolation boundary for reproducible toolchains. Separate images/profiles exist for latex, mermaid, python, docx, and crop, so each artifact type can be built with its own dependencies. The compose setup is also used in CI to guarantee consistent outputs.
7. Documentation is a separate subsystem under docs/, built with Zensical in Russian and English. It produces a static site, with alternate-language navigation and separate configs for local serving versus GitHub Pages deployment. This docs pipeline is independent from the thesis PDF build, but shares repository-level automation and hosting.
8. GitHub Actions provide the release and publishing boundary. Workflows cover Pages deployment, PDF release generation, validation and release of a Windows check executable, and scheduled backups. The CI logic is partly delegated to Python in scripts/ci/, which prepares release context and environment details before invoking the main build tasks.
9. The repository has a private content dependency: CI pulls a separate diploma_code repository into vault_diploma for code listings or appendix material. That makes the thesis build dependent not only on local sources but also on an external code corpus that must be available during build.
10. Testing is focused on the build automation itself, not on the thesis content. tests/ uses pytest to verify the pure-Python helper scripts such as build, cleanup, Mermaid compilation, DOCX conversion, cropping, PDF diffing, and checksum updates.
11. Backup is treated as an explicit subsystem rather than a filesystem snapshot. The project can package its Git history into a git bundle and upload it through rclone to cloud remotes, with scheduled automation both locally and in GitHub Actions. This preserves repository history, not uncommitted working state.
12. Overall architecture: source materials live in LaTeX, Mermaid, DOCX, and Python; build scripts and Task coordinates artifact generation; Docker provides reproducible environments; the final outputs are a thesis PDF, generated figures, and a static documentation site; CI/CD publishes PDFs, docs, checks tools, and backups to external services.
Main entry points: build_all.py Build scripts · Куприянов_И221_диплом.tex Main thesis · build.yml Build tasks · .gitkeep Figures
Components 21
Orchestration
Task-based build entrypoints and shared execution flow.
- Taskfile · Top-level task entrypoint coordinating build stages.
Taskfile.yml - Build tasks · High-level build orchestration for thesis, diagrams, docs, and utilities.
tasks/build.yml - Diagram tasks · Task definitions for Mermaid and Python-generated figures.
tasks/diagrams.yml - DOCX tasks · Task definitions for title-page DOCX conversion.
tasks/docx.yml
Thesis build
LaTeX source tree and supporting content for the PDF deliverable.
- Main thesis · Primary thesis source document and central build target.
Куприянов_И221_диплом.tex - Preamble · Package loading, bibliography setup, counters, lists, and formatting.
preamble/packages.tex - Appendix · Appendix material and injected listings.
appendix/appendix_b.tex - Tables · Reusable thesis tables and structured content blocks.
tables/tech_table.tex - Bibliography · Reference database consumed by the thesis build.
bibliography.bib - Fonts · Bundled font files required by the thesis typesetting environment.
fonts/latin-modern-mono/lmmono10-regular.otf
Generated assets
Intermediate and generated artifact pipelines consumed by LaTeX and docs.
- Mermaid source · Mermaid diagram definitions compiled into thesis figures.
mermaid/flow.mmd - Python diagrams · Python-based diagram generators that emit figure assets.
python_diagrams/languages.py - Figures · Compiled PDFs/images consumed by the thesis build.
figures/.gitkeep - Title pages · DOCX templates for title page and assignment sheet.
docx/титульник.docx - Root PDFs · Converted DOCX deliverables placed at the repository root.
Documentation
Zensical documentation site in two languages.
- Docs site · Static documentation site in Russian and English.
docs/ru/README.md
Tooling
Python utilities, CI helpers, tests, and release automation.
- Build scripts · Python operational layer for compilation, cleanup, conversion, hashing, and diffing.
scripts/build_all.py - CI helpers · CI-specific helpers for release context, publishing, and check-tool automation.
scripts/ci/prepare_pdf_release_env.py - Tests · Verification of build and helper scripts.
tests/test_build_latex_manual.py
Isolation
Containerized toolchains and compose profiles for reproducible builds.
- Dockerfiles · Isolated build images for latex, mermaid, python, docx, and crop workflows.
docker/latex.dockerfile - Compose · Compose definitions used locally and in CI for reproducible toolchains.
docker-compose.yaml
Connections 27
- Taskfile → Build tasks: delegates · Top-level tasks dispatch into split task files.
- Taskfile → Diagram tasks: delegates · Diagram-related automation is defined separately.
- Taskfile → DOCX tasks: delegates · DOCX conversion tasks are split out.
- Build tasks → Main thesis: builds · Main task path compiles the thesis PDF.
- Build tasks → Docs site: builds · Repository automation also covers documentation site generation.
- Main thesis → Preamble: includes · Root document depends on shared LaTeX setup.
- Main thesis → Appendix: includes · Appendix material is part of the thesis source graph.
- Main thesis → Tables: includes · Tables are assembled into the thesis.
- Main thesis → Bibliography: references · Bibliography is resolved through biblatex/biber.
- Main thesis → Fonts: uses · LuaLaTeX build relies on bundled fonts.
- Diagram tasks → Mermaid source: compiles · Mermaid sources are turned into figures.
- Diagram tasks → Python diagrams: runs · Python diagram scripts generate additional figures.
- Mermaid source → Figures: outputs · Compiled Mermaid diagrams land in the figures directory.
- Python diagrams → Figures: outputs · Python diagram scripts emit thesis figures.
- DOCX tasks → Title pages: converts · DOCX sources are converted into PDF deliverables.
- Title pages → Root PDFs: outputs · Converted title-page PDFs are written at the repository root.
- Main thesis → Figures: consumes · Final LaTeX build consumes generated PDFs and images, not raw sources.
- Build scripts → Build tasks: implements · Python scripts provide the build and utility actions behind tasks.
- Build scripts → Mermaid source: compiles · Mermaid compilation logic lives in Python utilities.
- Build scripts → Title pages: converts · DOCX-to-PDF conversion is handled by scripts.
- Build scripts → Figures: processes · Crop, diff, and hash utilities operate on generated artifacts.
- CI helpers → Build scripts: orchestrates · CI helpers prepare context before invoking core scripts.
- Tests → Build scripts: verifies · Pytest coverage targets the pure-Python automation layer.
- Dockerfiles → Compose: assembled by · Compose profiles select the appropriate build images.
- Compose → Build tasks: runs · Local and CI builds are executed through containerized profiles.
- Compose → Build scripts: isolates · Python helpers run within reproducible toolchains.
- Docs site → Build scripts: documents · Documentation explains the same build and release machinery.