XdTd Documentation Setup Guide¶

This document describes the documentation structure and how to use it.

Directory Structure¶

E:\python\source\
├── _docs/                         # Documentation source files
│   ├── getting-started/           # Installation & quick start
│   ├── user-guide/               # User documentation
│   ├── reference/                # Technical reference
│   ├── examples/                 # Example case studies
│   ├── videos/                   # Video tutorial links
│   ├── images/                   # Screenshots & diagrams
│   ├── generated/                # Auto-generated from code
│   │   └── (39 dialog docs)      # From UI files with tooltips
│   ├── index.md                  # Homepage
│   ├── faq.md                    # FAQ
│   └── ...
│
├── _utils/                        # Utility scripts
│   ├── doc_generators/
│   │   └── generate_dialog_docs.py  # Extracts docs from .ui files
│   └── README.md
│
├── mkdocs.yml                     # MkDocs configuration
├── requirements-docs.txt          # Documentation dependencies
└── README.md                      # Repository README

Documentation builds to: _docs/site/

What Has Been Set Up¶

✅ Completed¶

Directory Structure - All folders created with proper underscore prefix
MkDocs Configuration - Full configuration in mkdocs.yml
Starter Documentation:
Home page with quick links
Installation guide (Windows/Linux/macOS)
Quick Start tutorial
System Requirements
FAQ
Auto-Generation Script: _utils/doc_generators/generate_dialog_docs.py
Extracts widget information from .ui files
Reads tooltips we added earlier
Generated 39 dialog documentation pages automatically!
Documentation Dependencies: requirements-docs.txt

📝 To Be Completed (Manual Content)¶

The following pages need manual writing (templates created): - user-guide/overview.md - Application overview - user-guide/workflow.md - Typical analysis workflow - user-guide/interface.md - UI explanation - user-guide/tutorials/*.md - Step-by-step tutorials - reference/*.md - Technical references - examples/*.md - Example projects - videos/index.md - Video tutorial links

How to Use¶

View Documentation Locally¶

# Install dependencies (first time only)
pip install -r requirements-docs.txt

# Start local server
cd E:\python\source
mkdocs serve

# Open browser to: http://127.0.0.1:8000

Regenerate Dialog Documentation¶

Whenever you update tooltips in .ui files:

cd E:\python\source
python _utils/doc_generators/generate_dialog_docs.py

This will update all 39 generated documentation files.

Build Static HTML¶

# Build documentation to _docs/site/
mkdocs build

# The site/ folder contains complete HTML documentation
# Can be:
# - Copied to your website (www.xdtd.com/docs/)
# - Included in installer for offline use
# - Deployed to GitHub Pages

Deploy to GitHub Pages¶

# One command deployment (requires git push access)
mkdocs gh-deploy

# Documentation will be available at:
# https://nksalgado-proton.github.io/XdTd2d-Python/

Generated Dialog Documentation¶

The script automatically generated documentation for 39 dialogs that have tooltips:

Key dialogs documented: - DtdStiffenedPanelDialog (27 fields) - DtdMaterialPropertiesDialog (11 fields) - DtdSettingsDataDialog (19 fields) - DtdSelectTopology_2dDialog (12 fields) - And 35 more...

Each generated page includes: - Dialog description - Table of all fields with tooltips - Field types (Number, Dropdown, Checkbox, etc.) - Constraints (min/max values) - Related topics links

Features of the Documentation¶

Material Theme Features¶

✅ Light/Dark mode toggle
✅ Instant search
✅ Mobile responsive
✅ Code syntax highlighting
✅ Admonitions (Info, Warning, Tip boxes)
✅ Tabbed content
✅ Table of contents
✅ GitHub integration

Markdown Extensions¶

Math equations (LaTeX)
Diagrams (Mermaid)
Task lists
Code annotations
And more...

Next Steps¶

Priority 1: Add Manual Content¶

user-guide/overview.md - Describe what XdTd does
user-guide/workflow.md - Typical analysis steps
videos/index.md - Link to your tutorial videos

Priority 2: Add Screenshots¶

Take screenshots of key dialogs
Save to _docs/images/screenshots/
The generated docs have placeholders ready

Priority 3: Technical References¶

reference/crack-models.md - Crack growth equations
reference/boundary-conditions.md - BC types
reference/settings.md - Extract from GLOBAL_SETTINGS

Priority 4: Example Projects¶

Create example case studies in examples/ with: - Problem description - Input files - Expected results

Maintenance¶

When to Regenerate¶

Run the generator when: - ✏️ Tooltips are added/updated in .ui files - 🆕 New dialogs are created - 🔄 Dialog fields change

Keeping Docs in Sync¶

Documentation lives in same repository as code
Version tags apply to both code and docs
Update mkdocs.yml version when releasing

Deployment Options¶

Option 1: GitHub Pages (Free)¶

mkdocs gh-deploy
# URL: https://nksalgado-proton.github.io/XdTd2d-Python/

Option 2: Your Website¶

mkdocs build
# Copy _docs/site/ to www.xdtd.com/docs/

Option 3: Include in Installer¶

mkdocs build
# Include _docs/site/ in installation package
# Users open docs/index.html locally

Option 4: All Three!¶

Use all three methods simultaneously - they're not mutually exclusive.

Tips¶

Writing Documentation¶

Use admonitions for important notes:

!!! tip "Pro Tip"
    This is a helpful tip

!!! warning "Important"
    This is a warning

Add screenshots:

![Dialog Screenshot](../images/screenshots/dialog.png)

Link between pages:

See [Installation](getting-started/installation.md)

Testing Before Deployment¶

Always test locally first:

mkdocs serve
# Check all pages render correctly
# Test all links work
# Verify images load

Questions?¶

Summary¶

You now have: - ✅ Professional documentation framework - ✅ 39 auto-generated dialog reference pages - ✅ Starter pages for getting started - ✅ Tools to keep docs updated - ✅ Multiple deployment options

The documentation is production-ready and can be deployed immediately, with manual content added progressively as time permits!