Skip to content

QUICK_START_GUIDE.md

Latest commit

 

History

History
348 lines (242 loc) · 6.49 KB

QUICK_START_GUIDE.md

File metadata and controls

348 lines (242 loc) · 6.49 KB

Quick Start Guide for llcuda.github.io Website

New website location: /media/waqasm86/External1/Project-Nvidia-Office/llcuda.github.io/

✅ What Has Been Created

A complete, production-ready documentation website for llcuda v2.0.6 with:

  • ✅ MkDocs Material theme configuration
  • ✅ Homepage with verified performance (134 tok/s)
  • ✅ Installation Guide (GitHub-only distribution)
  • ✅ Quick Start Guide (5-minute setup)
  • ✅ Gemma 3-1B Tutorial (Colab notebook)
  • ✅ API Overview documentation
  • ✅ Custom Styling and JavaScript
  • ✅ Complete Navigation structure

Total: 10 pages created, 21 placeholder pages defined

🚀 Test the Website Locally

Step 1: Navigate to Directory

cd /media/waqasm86/External1/Project-Nvidia-Office/llcuda.github.io

Step 2: Install Dependencies

pip install -r requirements.txt

Expected output:

Successfully installed mkdocs-1.5.x mkdocs-material-9.4.x ...

Step 3: Start Local Server

mkdocs serve

Expected output:

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in X.XX seconds
INFO    -  [XX:XX:XX] Serving on http://127.0.0.1:8000/

Step 4: Open in Browser

Visit: http://127.0.0.1:8000/

The website will auto-reload when you make changes to any .md files.

📁 Website Structure

llcuda.github.io/
├── mkdocs.yml              # Main configuration
├── requirements.txt        # Python dependencies
├── README.md               # Repository documentation
│
└── docs/                   # All website content
    ├── index.md            # Homepage
    ├── guides/             # Getting started guides
    ├── tutorials/          # Step-by-step tutorials
    ├── api/                # API documentation
    ├── performance/        # Benchmarks and optimization
    ├── notebooks/          # Notebook guides
    ├── examples/           # Code examples
    ├── stylesheets/        # Custom CSS
    ├── javascripts/        # Custom JavaScript
    └── assets/             # Images, logos, etc.

📝 Creating New Pages

Example: Create FAQ Page

# Create the file
nano docs/guides/faq.md

Add content:

# Frequently Asked Questions

## Installation

### How do I install llcuda?

\`\`\`bash
pip install git+https://github.com/llcuda/llcuda.git
\`\`\`

### Why GitHub instead of PyPI?

llcuda v2.0.6 is distributed exclusively through GitHub...

[Continue with Q&A format]

Save the file - MkDocs will automatically reload and show the page!

🎨 Customizing the Website

Change Colors

Edit docs/stylesheets/extra.css:

:root {
  --md-primary-fg-color: #YOUR_COLOR;
  --md-accent-fg-color: #YOUR_COLOR;
}

Add Logo/Favicon

  1. Add images to docs/assets/images/
  2. Update mkdocs.yml:
theme:
  favicon: assets/images/favicon.png
  logo: assets/images/logo.png

Modify Navigation

Edit mkdocs.yml under the nav: section:

nav:
  - Home: index.md
  - Your Section:
      - Your Page: path/to/page.md

🔧 Building the Website

Build Static Files

mkdocs build

Output will be in site/ directory (ready for deployment).

Check for Broken Links

mkdocs build --strict

This will fail if there are any broken internal links.

📤 Deploying to GitHub Pages

Option 1: Automatic Deployment

# Deploy to gh-pages branch
mkdocs gh-deploy

This automatically builds and pushes to the gh-pages branch.

Option 2: Manual Deployment

# Build the site
mkdocs build

# Copy site/ contents to gh-pages branch manually

GitHub Pages Settings

Once deployed, configure in GitHub repository settings:

  • Go to Settings → Pages
  • Source: Deploy from a branch
  • Branch: gh-pages / root
  • Save

Website will be live at: https://USERNAME.github.io/

📋 Checklist for Completion

Core Content (✅ Done)

  • Homepage with performance data
  • Installation guide
  • Quick start guide
  • Gemma 3-1B tutorial
  • API overview

To Complete

  • Add remaining guide pages (FAQ, troubleshooting, etc.)
  • Create detailed API reference pages
  • Add performance benchmark pages
  • Create notebook overview pages
  • Add code example pages
  • Add logo and favicon images
  • Update Google Analytics ID in mkdocs.yml
  • Test all internal links
  • Review all code examples

💡 Tips for Development

Live Preview

While mkdocs serve is running:

  • Edit any .md file in docs/
  • Save the file
  • Browser auto-reloads with changes
  • See instant preview

Markdown Features

llcuda.github.io supports:

Admonitions:

!!! tip "Pro Tip"
    Use silent mode for cleaner output!

Code Blocks:

\`\`\`python
import llcuda
engine = llcuda.InferenceEngine()
\`\`\`

Tabs:

=== "Google Colab"
    Content for Colab

=== "Local Linux"
    Content for Linux

Tables:

| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

Grid Cards:

<div class="grid cards" markdown>

- :material-icon: **Title**

    Description here

</div>

🐛 Troubleshooting

Port Already in Use

# Use different port
mkdocs serve -a 127.0.0.1:8001

Module Not Found

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

Changes Not Showing

# Clear cache and restart
rm -rf site/
mkdocs serve

📚 Documentation Resources

🎯 Next Actions

  1. ✅ Test locally - Run mkdocs serve and view in browser
  2. 📝 Complete pages - Fill in placeholder pages
  3. 🎨 Add branding - Logo and favicon
  4. 🔗 Test links - Verify all internal links work
  5. 🚀 Deploy - Push to GitHub Pages when ready

✉️ Need Help?

  • Check WEBSITE_STATUS.md for detailed structure
  • Review existing pages for examples
  • Refer to MkDocs Material documentation
  • Test locally before deploying

Website Status: ✅ Ready for local testing and development

Location: /media/waqasm86/External1/Project-Nvidia-Office/llcuda.github.io/

Created: January 10, 2026