Technical Papers Repository

A collection of technical papers and documentation with automated LaTeX compilation

📖 Overview

This repository hosts technical papers and documentation with automated PDF generation. Each project maintains its source LaTeX files (.tex) and compiled PDFs (.pdf) in the same directory.

Current Projects:

• Project JANUS - Neuromorphic Trading Intelligence System (consolidated in project_janus/janus.tex)

🏗️ Repository Structure

technical_papers/
├── .github/
│   └── workflows/
│       └── ci.yml                 # Automated PDF compilation
├── project_janus/                 # Main project directory
│   ├── janus.tex                  # ⭐ CONSOLIDATED DOCUMENT (recommended)
│   ├── janus.pdf                  # Compiled PDF (auto-generated)
│   └── README.md                  # Project-specific documentation
├── main.tex                       # Legacy standalone documents
├── forward.tex
├── backward.tex
├── neuro.tex
├── rust.tex
├── main_content.tex               # Content-only file (used by janus.tex)
└── README.md                      # This file

🚀 Quick Start

Option 1: Download Pre-Built PDFs

PDFs are automatically compiled and committed to the repository:

git clone https://github.com/nuniesmith/technical_papers.git
cd technical_papers

# Navigate to any project directory
cd project_janus

# PDFs are located next to their source .tex files
ls -lh *.pdf

Option 2: Build Locally

Prerequisites

• LaTeX Distribution: TeX Live (Linux/Windows) or MacTeX (macOS)
• Bash: Available on Linux/macOS/WSL

Installation

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y texlive-full

macOS (Homebrew):

brew install --cask mactex

macOS (MacPorts):

sudo port install texlive

Arch Linux:

sudo pacman -S texlive-most

Fedora/RHEL:

sudo dnf install texlive-scheme-full

Build Project Documents

If the project includes a build script:

cd technical_papers
chmod +x scripts/build.sh
./scripts/build.sh

Or build individual documents manually:

cd project_name

# Build a document (run twice for TOC/references)
pdflatex document.tex
pdflatex document.tex

# Or use latexmk for automatic handling
latexmk -pdf document.tex

🤖 Automated CI/CD

Every push to the main branch triggers automated PDF compilation via GitHub Actions.

Features:

• ✅ Auto-discovery: Automatically finds all .tex files with \documentclass
• ✅ Smart compilation: Runs pdflatex twice for TOC and cross-references
• ✅ Same-directory output: PDFs are created next to their source files
• ✅ Auto-commit: Compiled PDFs are committed back to the repository
• ✅ Loop prevention: Uses [skip ci] to prevent infinite build loops
• ✅ Build reports: Summary of successful/failed compilations

Workflow: .github/workflows/ci.yml

Adding New Documents

Simply create a new .tex file anywhere in the repository:

\documentclass{article}
\begin{document}
Your content here
\end{document}

The CI system will automatically detect and compile it!

📁 Project Guidelines

Creating a New Project

1. Create project directory:

   mkdir new_project_name
   cd new_project_name

2. Add LaTeX documents:

   # Create your .tex files
   touch paper.tex

3. Optional: Add build script:

   # Create project-specific build automation
   touch build.sh
   chmod +x build.sh

4. Commit and push:

   git add new_project_name/
   git commit -m "Add new project: Project Name"
   git push

The CI system will automatically compile your documents.

Project Structure Recommendations

Simple project (single document):

my_paper/
├── paper.tex
└── paper.pdf (auto-generated)

Complex project (multiple documents):

my_project/
├── main.tex
├── main.pdf
├── appendix_a.tex
├── appendix_a.pdf
├── complete.tex          # Optional: unified document
├── complete.pdf
├── extract_content.sh    # Optional: content extraction
└── README.md             # Optional: project-specific docs

📝 LaTeX Best Practices

Required Packages

Ensure your documents load commonly available packages:

\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
\usepackage{amsmath, amssymb}
\usepackage{graphicx}
\usepackage{hyperref}

Cross-References

Run compilation twice for proper TOC and references:

pdflatex document.tex  # First pass
pdflatex document.tex  # Second pass (resolves references)

Or use latexmk for automatic handling:

latexmk -pdf document.tex

Unicode Support

For unicode characters in LaTeX:

\usepackage{newunicodechar}
\newunicodechar{→}{\ensuremath{\rightarrow}}
\newunicodechar{≥}{\ensuremath{\geq}}

🔧 Build Script Template

Create a build.sh in your project directory:

#!/bin/bash
set -e

# Compile all documents
for tex_file in *.tex; do
    if [ -f "$tex_file" ]; then
        echo "Building $tex_file..."
        pdflatex -interaction=nonstopmode "$tex_file"
        pdflatex -interaction=nonstopmode "$tex_file"
    fi
done

# Cleanup auxiliary files
rm -f *.aux *.log *.out *.toc *.synctex.gz

echo "Build complete!"

📊 Current Projects

Project JANUS - Neuromorphic Trading Intelligence

A comprehensive technical specification for a brain-inspired algorithmic trading system.

📄 Main Document (Recommended):

• project_janus/janus.pdf - Complete consolidated specification (all parts in one)

Legacy Documents (Individual Parts):

• main.pdf - Architectural overview and philosophy
• forward.pdf - Real-time trading service (Janus Bifrons)
• backward.pdf - Memory consolidation and learning (Janus Consivius)
• neuro.pdf - Neuromorphic architecture mapping
• rust.pdf - Rust implementation guide

What's Inside janus.pdf:

• Part 1: Main Architecture - System design and philosophy
• Part 2: Forward Service - Real-time decision-making and execution
• Part 3: Backward Service - Memory consolidation and learning
• Part 4: Neuromorphic Architecture - Brain-region mapping
• Part 5: Rust Implementation - Production deployment guide

Location: project_janus/ | Documentation: project_janus/README.md

---

🤝 Contributing

Contributions are welcome! To add or improve documentation:

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/new-paper

3. Add your LaTeX files
4. Test compilation locally
5. Submit a pull request

Contribution Guidelines

• ✅ Use standard LaTeX packages (avoid exotic dependencies)
• ✅ Include README in project directories for complex projects
• ✅ Test compilation before pushing
• ✅ Use meaningful commit messages
• ✅ Keep source files (.tex) and PDFs in the same directory

📄 License

Unless otherwise specified, content in this repository is licensed under:

• Documentation/Papers: Creative Commons BY-NC-SA 4.0
• Code/Scripts: MIT License

Individual projects may specify their own licenses.

🛠️ Troubleshooting

LaTeX Compilation Errors

Issue: "File not found" errors

# Solution: Install missing packages
sudo apt-get install texlive-latex-extra texlive-fonts-extra

Issue: Unicode characters not rendering

# Solution: Add unicode support
\usepackage[utf8]{inputenc}
\usepackage{newunicodechar}

Issue: References showing as "??"

# Solution: Run pdflatex twice
pdflatex document.tex
pdflatex document.tex

CI/CD Issues

Issue: Build fails on GitHub Actions

• Check the Actions tab for detailed logs
• Ensure all required packages are in texlive-full
• Test locally before pushing

Issue: Infinite commit loops

• Workflow uses [skip ci] in commit messages
• Ensure you're not modifying committed PDFs manually

📚 Resources

LaTeX Documentation

• LaTeX Project
• Overleaf Documentation
• CTAN - Comprehensive TeX Archive Network

GitHub Actions

• GitHub Actions Documentation
• LaTeX Action by xu-cheng

👤 Maintainer

Jordan Smith

• GitHub: @nuniesmith

🙏 Acknowledgments

• LaTeX Project contributors
• GitHub Actions community
• Open source LaTeX package maintainers

---

Adding a new project? Just create a directory, add your .tex files, commit, and push. The CI system handles the rest!