Skip to content

Common scenarios

This page helps you choose the shortest path when you do not need to read the whole documentation from start to finish.

Build the final PDF

Recommended path

Use the Docker build: it prepares the title pages, Mermaid diagrams, Python diagrams, and the final PDF in sequence.

task build

uv run python scripts/build_all.py

After the build, the final PDF appears in the project root. If the command fails, go to Compilation issues.

When to build images separately

task build runs the profile containers through docker compose run --build, so a separate task build:images step is usually not required. Use it only when you want to rebuild every Docker image ahead of time.

Build without Docker

  1. Install TeX Live, Python, latexmk, lualatex, and biber. Python is required by PyLuaTeX during LaTeX compilation.
  2. Prepare external artifacts: the title page, assignment, diagrams, and appendix code.
  3. Run the local build.
task latex:local

latexmk "Куприянов_И221_диплом.tex"

Details: Build without Docker.

Update diagrams

If mermaid/*.mmd files changed, rebuild Mermaid diagrams:

task mermaid

uvx --from git+https://github.com/ethercod3/compile_mermaid.git compile-mermaid

If python_diagrams/*.py files changed, rebuild Python diagrams:

task diagrams

uv run python scripts/compile_python_diagrams.py

After updating diagrams, rebuild the main PDF. Details: Diagrams.

Crop PDF margins

The command updates the source PDF in place, so check the target path before running it.

task crop -- path/to/file.pdf

task crop:docker -- path/to/file.pdf

The local variant requires pdfcrop and Ghostscript. The Docker variant uses a separate Alpine image with texlive-binextra and Ghostscript.

Split PDF into color and B/W pages

The command creates two files next to the source PDF: *_color.pdf with color pages only and *_bw.pdf with black-and-white pages only.

task pdf:split-color -- path/to/file.pdf

docker compose --profile latex run --build --rm latex python3 scripts/split_pdf_color.py path/to/file.pdf

Ghostscript detects color pages through C/M/Y ink coverage, while qpdf exports pages without changing rotation. Details: Splitting PDF into color and B/W pages.

Update the title page or assignment

  1. Edit the DOCX file in docx/.
  2. Rebuild the PDF versions of the title pages.
  3. Rebuild the main document.
task docx
task build

docker compose --profile docx up
uv run python scripts/build_all.py

If blank pages must be preserved, use task docx:keep-blank. Details: Title page and assignment.

Connect application source code

Place the code next to the LaTeX project directory and check the paths in .env:

VAULT_PATH="/vault_code"
VAULT_OS_PATH="../vault_diploma"

Path meaning

VAULT_OS_PATH is the path on your machine, and VAULT_PATH is the path inside the Docker container.

Details: Source code in appendices.

Compare PDFs between commits

Before running the command, make sure the Git working tree is clean.

task diff -- <commit_1> <commit_2>

uvx diff-pdf-commits --build "<build command>" --pdf "<PDF from TARGET>" --view <commit_1> <commit_2>

Details: PDF comparison between commits.

Open Stirling PDF

Stirling PDF is a local web interface that is convenient for manual PDF review and browser-based checking.

task stirling

docker compose --profile stirling up -d stirling_pdf

After startup, open:

http://localhost:8080

Available helper commands:

task stirling:logs
task stirling:down

The port and initial administrator password are stored in .env. Details: Stirling PDF.

Back up Git history

Create and verify a local bundle without uploading it:

task backup:local

Upload the bundle to Google Drive and Yandex Disk through rclone:

task backup

Commit or stash important local changes before backing up: git bundle stores Git history, not uncommitted files. Details: Backups.

Run the documentation locally

task docs

docker compose --profile docs up docs

Then open:

http://localhost:8000

Details: Documentation.