Skip to content

DOCUMENTATION_INSTRUCTIONS.md

Latest commit

 

History

History
285 lines (205 loc) · 6.58 KB

DOCUMENTATION_INSTRUCTIONS.md

File metadata and controls

285 lines (205 loc) · 6.58 KB

FuzzyInfer v2.0 Documentation - Setup & Deployment Instructions

Quick Start

1. Install Documentation Tools

cd /home/spinoza/github/beta/fuzzy-infer

# Install with pip
pip install mkdocs-material mkdocstrings[python] mkdocs-jupyter mkdocs-git-revision-date-localized-plugin

# Or install all dev dependencies
pip install -e ".[dev]"

2. Test Locally

# Serve documentation locally
mkdocs serve

# Open browser to http://localhost:8000
# Documentation will auto-reload when you save changes

3. Build Documentation

# Build static site
mkdocs build

# Build with strict mode (catches errors)
mkdocs build --strict

# Output is in ./site/ directory

GitHub Pages Deployment

Option A: Automatic Deployment (Recommended)

Already configured! The workflow at .github/workflows/docs.yml will automatically deploy on push to master.

Steps:

  1. Enable GitHub Pages in Repository Settings:

  2. Push your code:

    git add .
git commit -m "Add comprehensive MkDocs documentation"
git push origin master

  3. Monitor deployment:

Option B: Manual Deployment

# Build and deploy to gh-pages branch
mkdocs gh-deploy

# With custom message
mkdocs gh-deploy -m "Update documentation"

Documentation Structure Created

docs/
├── index.md                        # Homepage
├── quick-start.md                  # 5-minute quick start
├── installation.md                 # Installation guide
├── guide/
│   ├── concepts.md                 # Core fuzzy logic concepts
│   ├── inference.md                # How inference engine works
│   ├── fluent-api.md               # Fluent API guide
│   ├── cli.md                      # Command-line interface
│   ├── unix-pipes.md               # Unix philosophy & pipelines
│   ├── examples.md                 # Code examples
│   └── notebook.ipynb              # Interactive Jupyter tutorial
├── api/
│   ├── core.md                     # Core module API reference
│   ├── models.md                   # Data models API
│   ├── fluent.md                   # Fluent API reference
│   ├── jsonl.md                    # JSONL serialization API
│   └── cli.md                      # CLI module reference
├── development/
│   └── contributing.md             # Contributing guide
├── DEPLOYMENT.md                   # This deployment guide
└── CHANGELOG.md                    # Version history

Verification Checklist

After deployment, verify:

  • Documentation is accessible at GitHub Pages URL
  • All navigation links work
  • Search functionality works
  • Code examples render correctly
  • Jupyter notebook renders
  • API documentation displays properly
  • Images/diagrams display (if any)
  • Dark/light mode toggle works
  • Mobile responsive design works

Common Issues & Solutions

Issue: "mkdocs: command not found"

Solution:

pip install mkdocs-material

Issue: "Module not found" during build

Solution:

# Install all documentation dependencies
pip install mkdocstrings[python] mkdocs-jupyter mkdocs-git-revision-date-localized-plugin

Issue: GitHub Actions workflow fails

Solution:

  1. Check workflow file at .github/workflows/docs.yml
  2. Ensure GitHub Pages is enabled with source "GitHub Actions"
  3. Check Actions tab for error details
  4. Verify all dependencies are in pyproject.toml

Issue: Documentation not updating

Solution:

  1. Clear browser cache
  2. Wait 2-3 minutes for GitHub Pages to update
  3. Check workflow completed successfully
  4. Try hard refresh (Ctrl+Shift+R or Cmd+Shift+R)

Issue: Broken links

Solution:

# Build with strict mode to find issues
mkdocs build --strict

# Fix any reported errors

Customization

Change Theme Colors

Edit mkdocs.yml:

theme:
  palette:
    - scheme: default
      primary: indigo      # Change this
      accent: orange       # Change this

Add New Page

  1. Create markdown file in docs/
  2. Add to mkdocs.yml navigation:
nav:
  - User Guide:
    - New Page: guide/new-page.md
  1. Test locally: mkdocs serve

Update API Documentation

API docs auto-generate from docstrings. To update:

  1. Update docstrings in Python code
  2. Rebuild documentation: mkdocs build

Maintenance

Regular Updates

# Update documentation dependencies
pip install --upgrade mkdocs-material mkdocstrings mkdocs-jupyter

# Test build still works
mkdocs build --strict

Keep Examples Fresh

  • Test all code examples regularly
  • Update for new Python versions
  • Verify links are not broken
  • Update screenshots if UI changes

Monitor Analytics

Add Google Analytics to track:

  • Popular pages
  • Search queries
  • User flow
  • Bounce rate

Advanced Features

Versioned Documentation

Use mike for version management:

pip install mike

# Deploy version 2.0
mike deploy 2.0 latest --update-aliases

# Set default
mike set-default latest

# Serve versioned docs
mike serve

Custom Domain

To use custom domain:

  1. Create docs/CNAME file with domain:

    docs.fuzzy-infer.org

  2. Configure DNS with CNAME record pointing to:

    queelius.github.io

  3. Enable in GitHub Pages settings

Resources

Support

For documentation issues:

Summary

Your documentation is ready to deploy! Just:

  1. Install dependencies: pip install mkdocs-material mkdocstrings[python] mkdocs-jupyter mkdocs-git-revision-date-localized-plugin
  2. Test locally: mkdocs serve
  3. Enable GitHub Pages (source: GitHub Actions)
  4. Push to master: git push origin master
  5. Visit: https://queelius.github.io/fuzzy-infer/

That's it! 🎉

Created: 2025-10-12 Status: Complete and ready for deployment Estimated Build Time: 2-3 minutes on GitHub Actions