Skip to content

Commit 741c96d

Browse files
ch1boch1bo
authored
Merge pull request #595 from input-output-hk/ch1bo/design-pdf
Leios design: Build into a PDF using pandoc
2 parents 4925b29 + af721eb commit 741c96d

File tree

4 files changed

+152
-6
lines changed

4 files changed

+152
-6
lines changed

‎.github/workflows/leios-design.yaml‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
name: "Build Leios Design PDF"
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- "docs/leios-design/**"
7+
- "nix/artifacts.nix"
8+
- ".github/workflows/leios-design.yaml"
9+
push:
10+
branches:
11+
- main
12+
paths:
13+
- "docs/leios-design/**"
14+
- "nix/artifacts.nix"
15+
workflow_dispatch: # Allow manual triggering
16+
17+
permissions:
18+
contents: read
19+
actions: read
20+
21+
# Prevent redundant workflow runs
22+
concurrency:
23+
group: ${{ github.workflow }}-${{ github.ref }}
24+
cancel-in-progress: true
25+
26+
jobs:
27+
build-pdf:
28+
name: "Build Leios Design PDF"
29+
runs-on: ubuntu-latest
30+
steps:
31+
- name: 📥 Checkout repository
32+
uses: actions/checkout@v4
33+
with:
34+
fetch-depth: 1
35+
36+
- name: 🛠️ Install Nix
37+
uses: cachix/install-nix-action@v27
38+
with:
39+
nix_path: nixpkgs=channel:nixos-unstable
40+
extra_nix_config: |
41+
experimental-features = nix-command flakes
42+
accept-flake-config = true
43+
extra-substituters = https://cache.iog.io
44+
extra-trusted-public-keys = hydra.iohk.io:f/Ea+s+dFdN+3Y/G+FDgSq+a5NEWhJGzdjvKNGv0/EQ=
45+
46+
- name: 🗂️ Setup Cachix for IOG cache
47+
uses: cachix/cachix-action@v15
48+
with:
49+
name: iog
50+
authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}'
51+
skipPush: true
52+
53+
- name: 🏗️ Build PDF using Nix
54+
run: |
55+
echo "Building Leios Design PDF..."
56+
nix build .#leiosDesignPdf -L
57+
58+
# Verify the PDF was created
59+
if [ ! -f result/leios-design.pdf ]; then
60+
echo "Error: PDF file was not created"
61+
exit 1
62+
fi
63+
64+
# Show file size and info
65+
ls -lh result/leios-design.pdf
66+
file result/leios-design.pdf
67+
68+
- name: 📊 Get PDF metadata
69+
run: |
70+
# Get basic file info
71+
echo "PDF file size: $(stat -c%s result/leios-design.pdf) bytes"
72+
echo "PDF creation date: $(stat -c%y result/leios-design.pdf)"
73+
74+
# If pdfinfo is available, show more details
75+
if command -v pdfinfo &> /dev/null; then
76+
echo "PDF metadata:"
77+
pdfinfo result/leios-design.pdf || true
78+
fi
79+
80+
- name: 🚀 Upload PDF artifact
81+
uses: actions/upload-artifact@v4
82+
with:
83+
name: leios-design-pdf-${{ github.sha }}
84+
path: result/leios-design.pdf
85+
if-no-files-found: error
86+
retention-days: 30
87+
88+
- name: 📄 Add PDF info to job summary
89+
run: |
90+
echo "## 📄 Leios Design PDF Generated" >> $GITHUB_STEP_SUMMARY
91+
echo "" >> $GITHUB_STEP_SUMMARY
92+
echo "✅ Successfully built PDF from markdown source" >> $GITHUB_STEP_SUMMARY
93+
echo "" >> $GITHUB_STEP_SUMMARY
94+
echo "**File details:**" >> $GITHUB_STEP_SUMMARY
95+
echo "- Size: $(stat -c%s result/leios-design.pdf) bytes" >> $GITHUB_STEP_SUMMARY
96+
echo "- Generated: $(date -u '+%Y-%m-%d %H:%M:%S UTC')" >> $GITHUB_STEP_SUMMARY
97+
echo "- Commit: \`${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY
98+
echo "" >> $GITHUB_STEP_SUMMARY
99+
echo "The PDF is available as a workflow artifact named \`leios-design-pdf-${{ github.sha }}\`" >> $GITHUB_STEP_SUMMARY

‎docs/leios-design/README.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
---
2-
Title: Leios technical design and implementation plan
3-
Status: Draft
4-
Version: 0.2
5-
Authors:
2+
title: Leios technical design and implementation plan
3+
status: Draft
4+
version: 0.2
5+
author:
66
- Sebastian Nagel <[email protected]>
77
---
88

@@ -709,7 +709,7 @@ The testnet enables multiple validation categories. Functional testing verifies
709709

710710
The testnet integrates ecosystem tooling: wallets handling increased throughput, block explorers understanding new structures, monitoring systems tracking Leios metrics, and stake pool operator documentation and deployment guides. Crucially, the testnet further enables empirical parameter selection (size limits, timing parameters), where simulation provides initial guidance but real-world testing with community feedback informs acceptable mainnet values.
711711

712-
Software deployed to the public testnet progressively converges toward mainnet release candidates. Early deployments may use instrumented prototypes lacking production optimizations; later upgrades run increasingly complete and optimized implementations. Eventually, all changes as [outlined in this design document](#Architecture) must be realized in the `cardano-node` and other node implementations. This progressive refinement maintains community engagement while preserving engineering velocity. Traces from testnet nodes can still be verified against formal specifications using the trace verification approach, ultimately linking the abstraction layers.
712+
Software deployed to the public testnet progressively converges toward mainnet release candidates. Early deployments may use instrumented prototypes lacking production optimizations; later upgrades run increasingly complete and optimized implementations. Eventually, all changes as [outlined in this design document](#architecture) must be realized in the `cardano-node` and other node implementations. This progressive refinement maintains community engagement while preserving engineering velocity. Traces from testnet nodes can still be verified against formal specifications using the trace verification approach, ultimately linking the abstraction layers.
713713

714714
## Mainnet deployment readiness
715715

@@ -741,6 +741,9 @@ Operational readiness encompasses stake pool operator testing in their environme
741741

742742
# References
743743

744+
> [!WARNING]
745+
> TODO: Use pandoc-compatible citations https://pandoc.org/MANUAL.html#citation-syntax
746+
744747
1. **CIP-164**: Ouroboros Linear Leios - Greater transaction throughput https://github.com/cardano-scaling/CIPs/blob/leios/CIP-0164/README.md
745748

746749
1. **Leios Impact Analysis**: High-level component design https://github.com/input-output-hk/ouroboros-leios/blob/main/docs/ImpactAnalysis.md

‎docs/leios-design/metadata.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Pandoc PDF metadata
2+
toc: true
3+
numbersections: true
4+
highlight-style: haddock
5+
documentclass: scrartcl
6+
fontsize: 11pt
7+
geometry:
8+
- margin=2.5cm
9+
- top=3cm
10+
- bottom=3cm
11+
colorlinks: true
12+
linkcolor: NavyBlue
13+
urlcolor: NavyBlue
14+
citecolor: NavyBlue
15+
toccolor: black
16+
papersize: a4
17+
linestretch: 1.15
18+
indent: false
19+
header-includes: |
20+
\usepackage{microtype}
21+
\usepackage[T1]{fontenc}

‎nix/artifacts.nix‎

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,30 @@ let
3333
'';
3434
};
3535

36+
leiosDesignPdf = pkgs.stdenv.mkDerivation {
37+
name = "leios-design-pdf";
38+
src = ../docs/leios-design;
39+
buildInputs = [
40+
pkgs.pandoc
41+
pkgs.texliveFull
42+
pkgs.librsvg
43+
];
44+
buildPhase = ''
45+
# Work directly in the source directory where all assets are available
46+
cd $src
47+
mkdir -p $out
48+
49+
# Convert markdown to PDF using pandoc with XeLaTeX
50+
pandoc README.md \
51+
--pdf-engine=xelatex \
52+
--from=markdown \
53+
--to=pdf \
54+
--metadata-file metadata.yaml \
55+
--output=$out/leios-design.pdf
56+
'';
57+
};
58+
3659
in
3760
{
38-
inherit simRealism networkSpec;
61+
inherit simRealism networkSpec leiosDesignPdf;
3962
}

0 commit comments

Comments
 (0)