📚 Jiro Documentation
Welcome to the Jiro AI Assistant documentation. This is the official documentation for v1.0.0-beta "Kakushin" - a production-ready AI-powered personal assistant with real-time cloud integration, extensible plugin system, and enterprise-grade deployment capabilities.
Latest Release: v1.0.0-beta (2025-01-08) - View Changelog
🏗️ Structure
/
├── docs/ # Documentation content
│ ├── api-index.md # API documentation index
│ ├── project-description.md # Project overview
│ ├── project-structure.md # Auto-generated project structure
│ ├── user-guide.md # End-user documentation
│ ├── workflow-pipelines.md # CI/CD workflows
│ └── index.md # This file
├── _site/ # Generated documentation (after build)
│ ├── docs/ # Documentation output
│ ├── api/ # API reference output
│ └── assets/ # Static assets (images, CSS, etc.)
├── assets/ # Source assets (logos, images)
├── docfx.json # DocFX configuration
├── toc.yml # Main navigation structure
└── filterConfig.yml # API documentation filter
🚀 Building Documentation Locally
Prerequisites
- .NET 9.0 SDK
- DocFX tool
Setup
Install DocFX:
dotnet tool install -g docfx
Navigate to the repository root:
cd /path/to/Jiro
Build the documentation:
docfx docfx.json
Serve locally (optional):
docfx docfx.json --serve
The documentation will be available at
http://localhost:8080
🌐 Automatic Deployment
The documentation is automatically deployed to GitHub Pages when changes are pushed to the main
branch. The deployment is handled by the GitHub Actions workflow at .github/workflows/deploy-docs.yml
.
Deployment Triggers
The documentation deployment is triggered by:
- Push to main branch with changes to:
docs/**
(any documentation files)docfx.json
(DocFX configuration).github/workflows/deploy-docs.yml
(workflow file)
- Manual workflow dispatch (can be triggered manually from GitHub Actions)
Deployment Process
- Checkout - Retrieves the latest code
- Setup .NET - Installs .NET 9.x SDK
- Install DocFX - Installs the latest DocFX tool
- Restore Dependencies - Restores .NET project dependencies for API docs
- Build Documentation - Generates the static site using DocFX
- Deploy to GitHub Pages - Publishes to GitHub Pages
📝 Content Guidelines
Adding New Documentation
- Create your markdown file in the
docs/
directory - Add entry to toc.yml to include it in the navigation
- Use proper markdown formatting with headings, lists, and links
- Include emojis for visual appeal (following the existing style)
- Test locally before committing
Markdown Style Guide
- Use descriptive headings with appropriate levels
- Include blank lines around headings and lists
- Use code blocks for commands and configuration
- Include links to related documentation
- Add emojis to section headers for visual organization
API Documentation
API documentation is automatically generated from XML comments in the .NET code. To improve API docs:
- Add XML documentation to all public classes, methods, and properties
- Use
<summary>
,<param>
,<returns>
tags appropriately - Include
<example>
blocks for complex methods - Document exceptions with
<exception>
tags
🔧 Configuration
DocFX Configuration (docfx.json
)
Key configuration options:
- metadata.src: Source code paths for API documentation generation
- build.content: Documentation content files to include
- build.resource: Static resources (images, assets)
- build.output: Output directory for generated site
- globalMetadata: Site-wide settings and branding
Customization
To customize the documentation:
- Modify
docfx.json
for build configuration - Update
globalMetadata
for site information - Add custom templates in the
template
directory (if needed) - Include custom CSS/JS in the
resource
files
🎯 Best Practices
Documentation Writing
- Clear and Concise - Write for your audience
- Up-to-date - Keep documentation current with code changes
- Well-structured - Use consistent formatting and organization
- Searchable - Include relevant keywords and cross-references
Maintenance
- Regular Updates - Review and update documentation regularly
- Link Validation - Ensure all links work correctly
- Accessibility - Use proper heading structure and alt text
- Performance - Optimize images and keep pages reasonably sized
🐛 Troubleshooting
Common Issues
DocFX build fails
- Check that all referenced files exist
- Validate JSON syntax in
docfx.json
- Ensure .NET projects can be restored
Missing API documentation
- Verify XML documentation is enabled in project files
- Check that projects build successfully
- Confirm correct paths in
docfx.json
Deployment fails
- Check GitHub Actions logs for specific errors
- Verify repository settings allow GitHub Pages
- Ensure workflow has necessary permissions
Getting Help
- Check the DocFX documentation
- Review GitHub Actions workflow logs
- Examine the generated
_site
directory for build issues
📞 Support
This documentation is part of an engineering thesis project. For questions about the documentation system or technical details, please refer to the main project documentation or open an issue in the repository.