diff --git a/tech_docs/Jinja2.md b/tech_docs/Jinja2.md index b655902..d98e54b 100644 --- a/tech_docs/Jinja2.md +++ b/tech_docs/Jinja2.md @@ -772,3 +772,473 @@ You're right to ask—while Jinja2 is powerful, it's not the only tool in the to - **Hybrid approaches**: Use Jinja2 for device configs + Terraform for cloud. **Your edge?** You’re not just a network engineer—you’re the **automation guru** who knows when to use which tool. + +--- + +You're absolutely right to call this out—**Jinja2 + LaTeX is a powerhouse combo** for **precision document generation**, especially for RFPs, network design docs, or compliance reports where pixel-perfect formatting matters. Let me correct that oversight with tactical details: + +--- + +### **Why Jinja2 + LaTeX Beats Jinja2 + Pandoc for Critical Documents** +#### **1. Use LaTeX When You Need:** +- **Math-heavy content** (e.g., network performance formulas, QoS calculations). +- **Professional typography** (automatic hyphenation, kerning, TOC/Index generation). +- **Strict compliance templates** (e.g., government RFP responses with mandated formats). + +#### **2. Jinja2 + LaTeX Workflow** +**Step 1:** Create a LaTeX template with Jinja2 placeholders (`template.tex.j2`): +```latex +\documentclass{report} +\title{ {{- project_name | latex_escape -}} } +\begin{document} +\section{Network Design} +\begin{itemize} +{% for device in devices %} + \item {{ device.name | latex_escape }} ({{ device.ip }}) \\ + VLANs: {{ device.vlans | join(', ') }} +{% endfor %} +\end{itemize} + +\section{Bandwidth Calculation} +The required bandwidth is: +\[ +C = \frac{{ {{ traffic_volume }} }}{{ {{ time_window }} }} +\] +\end{document} +``` + +**Step 2:** Render with Jinja2 and compile to PDF: +```bash +# Render Jinja2 -> LaTeX +jinja2 template.tex.j2 data.yml > output.tex + +# Compile LaTeX (install pdflatex first) +pdflatex output.tex +``` + +#### **3. Key Advantages Over Pandoc** +| Feature | LaTeX + Jinja2 | Pandoc + Jinja2 | +|------------------------|------------------------------------|-----------------------------------| +| **Math Formulas** | Native LaTeX equations (e.g., `\[ x^2 \]`) | Requires MathJax/PDF workarounds | +| **Table Formatting** | Precise column alignment (e.g., `tabularx`) | Limited Markdown table support | +| **Automated Numbering**| Auto-numbered sections/figures | Manual numbering in Markdown | +| **Bibliography** | BibTeX integration | Requires Pandoc filters | + +#### **4. Real-World Use Cases** +- **RFP Responses**: Auto-generate compliant proposals with perfect margins. +- **Network Design Docs**: Embed topology diagrams (via `tikz`) with dynamic labels. +- **Academic Reports**: Generate research papers with citations from YAML data. + +#### **5. Pro Tips** +- **Escape LaTeX Specials**: Use a custom filter to escape `%`, `$`, etc.: + ```python + def latex_escape(s): + return s.replace('$', r'\$').replace('%', r'\%') + ``` +- **Precompile Headers**: Store boilerplate LaTeX in snippets: + ```jinja2 + {% include 'preamble.tex.j2' %} # Your firm's standard header + ``` +- **Version Control**: Track both `.tex.j2` templates and rendered `.tex` files. + +--- + +### **When to Still Use Pandoc** +- **Speed**: For quick Markdown → Word/PDF conversions. +- **Simplicity**: When LaTeX is overkill (internal docs, draft reports). +- **Collaboration**: Non-technical teams can edit Markdown source. + +--- + +### **Updated Verdict** +- **For internal docs/agility**: **Jinja2 + Pandoc** (faster iteration). +- **For client-facing/precision docs**: **Jinja2 + LaTeX** (unmatched polish). + +**Example Repo**: [jinja2-latex-network-docs](https://github.com/example/jinja2-latex) + +Want to see a live example? I can generate a sample network design PDF from your YAML data. + +--- + +### **Jinja2 as the Universal Templating Glue** +Yes! **Jinja2 can template *anything*—HCL (Terraform), Pulumi, CDK, HTML, SQL, even COBOL if you’re desperate**. Here’s how to wield it across your stack, with brutal pragmatism: + +--- + +### **1. Templating HCL (Terraform)** +**Problem**: Terraform’s `count` and `dynamic` blocks are clunky for complex logic. +**Solution**: Pre-generate Terraform files with Jinja2. + +**`terraform/main.tf.j2`** +```jinja2 +{% for subnet in subnets %} +resource "aws_subnet" "{{ subnet.name }}" { + vpc_id = aws_vpc.main.id + cidr_block = "{{ subnet.cidr }}" + tags = { + Name = "{{ subnet.name }}" + } +} +{% endfor %} +``` +**Render it**: +```bash +jinja2 terraform/main.tf.j2 vars/network.yml > terraform/main.tf +``` +**When to Do This**: +- Need loops/conditionals Terraform can’t handle natively (e.g., multi-cloud variations). +- **Warning**: Loses Terraform’s state management. Use sparingly. + +--- + +### **2. Generating Pulumi Code** +**Problem**: Pulumi (Python/TS) already has logic—why Jinja2? +**Solution**: Template *scaffolding* for repetitive stacks. + +**`pulumi/__main__.py.j2`** +```jinja2 +from pulumi import Output +from pulumi_aws import ec2 + +{% for subnet in subnets %} +subnet_{{ loop.index }} = ec2.Subnet( + "{{ subnet.name }}", + cidr_block="{{ subnet.cidr }}", + vpc_id=vpc.id +) +{% endfor %} +``` +**Use Case**: +- Bootstrapping new projects with standard patterns (e.g., every VPC needs 3 subnets). + +--- + +### **3. CDK (AWS Cloud Development Kit)** +**Problem**: CDK’s constructs are verbose for boilerplate. +**Solution**: Jinja2 to generate repetitive CDK code. + +**`cdk_stack.py.j2`** +```jinja2 +from aws_cdk import Stack +from constructs import Construct + +class {{ stack_name }}Stack(Stack): + def __init__(self, scope: Construct, id: str, **kwargs): + super().__init__(scope, id, **kwargs) + + {% for bucket in s3_buckets %} + s3.Bucket(self, "{{ bucket.name }}", versioned=True) + {% endfor %} +``` +**Render it**: +```bash +jinja2 cdk_stack.py.j2 vars/project.yml > cdk_app.py +``` + +--- + +### **4. HTML/Web Dev** +**Problem**: Static HTML sucks for dynamic docs. +**Solution**: Jinja2 as a poor-man’s React. + +**`templates/dashboard.html.j2`** +```jinja2 + + + +

{{ title }}

+ + {% for device in devices %} + + + + + {% endfor %} +
{{ device.name }} + {{ device.status }} +
+ + +``` +**Use Case**: +- Auto-generate network dashboards from NetBox API data. + +--- + +### **5. SQL & Database Scripts** +**Problem**: Schema changes across environments (dev/stage/prod). +**Solution**: Jinja2-templated DDLs. + +**`sql/schema.sql.j2`** +```jinja2 +CREATE TABLE {{ table_name }} ( + id SERIAL PRIMARY KEY, + {% for column in columns %} + {{ column.name }} {{ column.type }}{% if not loop.last %},{% endif %} + {% endfor %} +); +``` +**Render it**: +```bash +jinja2 sql/schema.sql.j2 vars/prod_db.yml > sql/prod_init.sql +``` + +--- + +### **6. Even COBOL (Don’t Ask Why)** +**`cobol/program.cbl.j2`** +```jinja2 +IDENTIFICATION DIVISION. +PROGRAM-ID. {{ program_name }}. + +DATA DIVISION. +WORKING-STORAGE SECTION. +{% for var in variables %} +01 {{ var.name }} PIC {{ var.type }}. +{% endfor %} +``` + +--- + +### **When *Not* to Use Jinja2** +1. **Terraform/Pulumi/CDK Already Have Logic**: Use native loops (`for_each`, `dynamic`) first. +2. **High-Performance Needs**: Use Go’s `text/template` or Rust’s `askama`. +3. **Frontend Apps**: React/Vue are better for DOM reactivity. + +--- + +### **The Jinja2 Playbook** +1. **Start Simple**: + ```bash + # Render a Terraform file + jinja2 tf_template.j2 vars.yml > main.tf + ``` +2. **Scale with Automation**: + ```bash + # Add to CI/CD (GitHub Actions) + - name: Generate configs + run: | + jinja2 templates/network.j2 vars/$ENV.yml > output.conf + ``` +3. **Nuclear Option**: + ```python + # Programmatic rendering (Python) + from jinja2 import Environment, FileSystemLoader + env = Environment(loader=FileSystemLoader("templates")) + template = env.get_template("cisco.j2") + print(template.render(interfaces=[...])) + ``` + +--- + +### **Final Answer** +**Jinja2 is the duct tape of infrastructure**—use it to glue together: +- **Terraform/Pulumi/CDK** (when native logic falls short). +- **HTML/SQL/LaTeX** (for dynamic doc generation). +- **Legacy Systems** (COBOL, mainframe configs). + +**Your Move**: +```bash +# Try templating something absurd today +jinja2 /dev/null <(echo '{{ "Hello, " + name }}') <<<'{"name": "Terminal"}' +``` + +--- + +### **The Ultimate Network Visualization Stack: Self-Documenting, Auto-Generated, and Jinja2-Powered** + +For network engineers and architects, **visualization isn’t just about diagrams—it’s about creating living documentation that updates with your configs**. Here’s how to combine the best tools for **self-documenting network visuals** with Jinja2 at the core. + +--- + +## **1. The Best-of-All-Worlds Approach** +### **Step 1: Define Your Network in Structured Data (YAML/JSON)** +```yaml +# network.yml +network: + name: "Core Data Center" + devices: + - name: "Core-SW1" + type: "Cisco Nexus" + mgmt_ip: "10.0.0.1" + interfaces: + - name: "Eth1/1" + connected_to: "Firewall-Main" + bandwidth: "10G" + - name: "Firewall-Main" + type: "Palo Alto PA-3400" + mgmt_ip: "10.0.0.2" +``` + +### **Step 2: Use Jinja2 to Generate Multiple Formats** +#### **A. Mermaid Diagrams (GitHub/Markdown)** +**`templates/topology.mmd.j2`** +```jinja2 +%%{init: {'theme': 'dark'}}%% +graph TD + {% for device in network.devices %} + {{ device.name }}["{{ device.type }}\n{{ device.mgmt_ip }}"] + {% endfor %} + {% for device in network.devices %} + {% for intf in device.interfaces %} + {{ device.name }} -- {{ intf.bandwidth }} --> {{ intf.connected_to }} + {% endfor %} + {% endfor %} +``` +**Output**: +```mermaid +graph TD + Core-SW1["Cisco Nexus\n10.0.0.1"] + Firewall-Main["Palo Alto PA-3400\n10.0.0.2"] + Core-SW1 -- 10G --> Firewall-Main +``` +**Use Case**: Embed in Git READMEs or MkDocs. + +#### **B. Graphviz (PDF/PNG, Precision Layouts)** +**`templates/topology.dot.j2`** +```jinja2 +digraph Network { + label="{{ network.name }}" + {% for device in network.devices %} + "{{ device.name }}" [shape=box, label="{{ device.type }}\n{{ device.mgmt_ip }}"] + {% endfor %} + {% for device in network.devices %} + {% for intf in device.interfaces %} + "{{ device.name }}" -> "{{ intf.connected_to }}" [label="{{ intf.bandwidth }}"] + {% endfor %} + {% endfor %} +} +``` +**Render it**: +```bash +jinja2 templates/topology.dot.j2 network.yml | dot -Tpng > topology.png +``` +**Use Case**: High-quality architecture diagrams for audits. + +#### **C. Draw.io (Interactive Editing)** +**`templates/drawio.xml.j2`** +```jinja2 + + + {% for device in network.devices %} + + {% endfor %} + {% for device in network.devices %} + {% for intf in device.interfaces %} + + {% endfor %} + {% endfor %} + + +``` +**Use Case**: Share editable diagrams with non-technical teams. + +#### **D. NetBox Integration (Source of Truth)** +**`templates/netbox_import.json.j2`** +```jinja2 +[ + {% for device in network.devices %} + { + "name": "{{ device.name }}", + "device_type": "{{ device.type }}", + "custom_fields": { "mgmt_ip": "{{ device.mgmt_ip }}" } + }{% if not loop.last %},{% endif %} + {% endfor %} +] +``` +**Use Case**: Auto-populate NetBox via API. + +--- + +## **2. Self-Documenting Magic** +### **A. Auto-Generated Network Docs (MkDocs + Jinja2)** +**`docs/network.md.j2`** +```jinja2 +# {{ network.name }} + +## Devices +| Name | Type | IP | +|------|------|----| +{% for device in network.devices %} +| {{ device.name }} | {{ device.type }} | `{{ device.mgmt_ip }}` | +{% endfor %} + +## Diagram +```mermaid +{% include 'topology.mmd.j2' %} +``` +``` +**Result**: +- Every Git commit updates docs **and** diagrams. +- Run `mkdocs serve` to see live changes. + +### **B. Visio-Like Automation (Python + Jinja2)** +```python +from jinja2 import Template +import yaml, subprocess + +data = yaml.safe_load(open("network.yml")) +template = Template(open("templates/topology.dot.j2").read()) +with open("topology.dot", "w") as f: + f.write(template.render(**data)) +subprocess.run(["dot", "-Tsvg", "topology.dot", "-o", "docs/img/topology.svg"]) +``` +**Output**: +- SVG diagrams in your docs, auto-updated on changes. + +--- + +## **3. Pro Tips for Zero-Touch Documentation** +1. **Git Hooks**: Auto-render diagrams on commit. + ```bash + # .git/hooks/pre-commit + jinja2 templates/topology.mmd.j2 network.yml > docs/topology.mmd + git add docs/topology.mmd + ``` +2. **CI/CD Integration**: + ```yaml + # GitHub Actions + - name: Generate diagrams + run: | + jinja2 templates/topology.dot.j2 network.yml | dot -Tpng > topology.png + ``` +3. **Dynamic Labels**: + ```jinja2 + {{ device.name }}["{{ device.type }}\n{% if device.vrf %}VRF: {{ device.vrf }}{% endif %}"] + ``` + +--- + +## **4. When to Use Which Tool** +| **Tool** | **Best For** | **Weakness** | +|----------------|----------------------------------|-----------------------------| +| **Mermaid** | Git docs, quick Markdown | Limited layout control | +| **Graphviz** | Publication-quality diagrams | Manual tweaking needed | +| **Draw.io** | Collaborative editing | Not code-driven | +| **NetBox** | Source-of-truth visualization | Requires NetBox setup | + +--- + +## **5. The Ultimate Workflow** +1. **Define** network in YAML. +2. **Generate**: + - Diagrams (Mermaid/Graphviz) + - Docs (MkDocs) + - Configs (Jinja2 → Cisco/JSON) +3. **Sync**: Git hooks or CI/CD auto-update everything. + +**Result**: Your network **documents itself**. + +--- + +### **Final Answer** +For **self-documenting network visuals**: +1. **Store configs in YAML** (single source of truth). +2. **Jinja2 → Mermaid/Graphviz** (auto-generate diagrams). +3. **Embed in MkDocs** (always-updated documentation). + +**Example Repo**: +```bash +git clone https://github.com/network-automation/jinja2-mermaid-networks +``` +**Your move**: Replace one manual diagram today with this pipeline. \ No newline at end of file