Skip to content

Commit 34708d5

Browse files
GarrettBeattyGarrettBeatty
committed
add docfx
1 parent 224a0b6 commit 34708d5

File tree

11 files changed

+1011
-1
lines changed

11 files changed

+1011
-1
lines changed

‎.gitignore

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ sdk/.vs/**
2828

2929
docgenerator/.vs/**
3030

31+
docgenerator/Deployment/**
3132
Deployment/**
3233
NuGetDownloads/**
3334
DocDeployment/**
@@ -69,4 +70,20 @@ sdk/test/Performance/**/BenchmarkDotNet.Artifacts/*
6970
#protocol-tests
7071
sdk/test/ProtocolTests/Generated/**/model
7172
sdk/test/ProtocolTests/Generated/**/sources
72-
sdk/test/ProtocolTests/Generated/**/build-info
73+
sdk/test/ProtocolTests/Generated/**/build-info
74+
75+
####################
76+
# DocFX Documentation Generator
77+
####################
78+
docgenerator/api/**
79+
docgenerator/docs-output/**
80+
docgenerator/templates/material/**
81+
docgenerator/_site/**
82+
83+
####################
84+
# macOS System Files
85+
####################
86+
.DS_Store
87+
**/.DS_Store
88+
89+
templates

‎docgenerator/README-DocFX.md

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
# DocFX Integration for AWS SDK .NET Documentation
2+
3+
This document describes the new DocFX integration that provides a modern, beautiful documentation experience using the Material theme.
4+
5+
## Overview
6+
7+
The AWS SDK .NET documentation generator has been enhanced to support DocFX with a Material Design theme, providing:
8+
9+
- **Modern UI**: Beautiful, responsive design with Material Design principles
10+
- **Enhanced Search**: Powerful search functionality across all documentation
11+
- **Better Navigation**: Improved table of contents and cross-references
12+
- **Mobile Friendly**: Optimized for mobile and tablet viewing
13+
- **Fast Loading**: Optimized performance and caching
14+
15+
## Requirements
16+
17+
Before using the DocFX integration, ensure you have:
18+
19+
1. **.NET 8.0 SDK** or later
20+
2. **DocFX** - Install using: `dotnet tool install -g docfx`
21+
3. **Git** - Required for downloading the Material theme
22+
4. **Built AWS SDK assemblies** - The SDK must be built and assemblies available
23+
24+
## Quick Start
25+
26+
### Using the Setup Scripts
27+
28+
The easiest way to get started is using the provided setup scripts:
29+
30+
#### Windows (PowerShell)
31+
```powershell
32+
.\setup-docfx.ps1 -SDKAssembliesRoot "C:\path\to\sdk\assemblies" -Verbose
33+
```
34+
35+
#### Linux/macOS (Bash)
36+
```bash
37+
./setup-docfx.sh --sdk-assemblies-root "/path/to/sdk/assemblies" --verbose
38+
```
39+
40+
### Manual Usage
41+
42+
You can also run the documentation generator directly:
43+
44+
```bash
45+
# Build the generator first
46+
dotnet build SDKDocGenerator.sln -c Release
47+
48+
# Run with DocFX
49+
./SDKDocGenerator/bin/Release/net8.0/SDKDocGenerator -usedocfx -sdkassembliesroot "/path/to/assemblies" -verbose
50+
```
51+
52+
## Command Line Options
53+
54+
The DocFX integration adds the following new option:
55+
56+
- `-usedocfx` or `-docfx`: Enable DocFX generation with Material theme
57+
58+
All existing options are supported:
59+
60+
- `-sdkassembliesroot`: Path to SDK assemblies directory
61+
- `-outputfolder`: Output directory for generated documentation
62+
- `-platform`: Target platform (default: net472)
63+
- `-services`: Comma-separated list of services to include
64+
- `-verbose`: Enable verbose output
65+
- `-clean`: Clean output folder before generation
66+
- `-testmode`: Generate limited documentation for testing
67+
68+
## Configuration
69+
70+
### DocFX Configuration File
71+
72+
The `docfx.json` file controls DocFX behavior:
73+
74+
```json
75+
{
76+
"metadata": [
77+
{
78+
"src": [
79+
{
80+
"files": ["**/*.dll"],
81+
"exclude": ["**/AWSSDK.Extensions.*.dll"],
82+
"src": "../sdk/src/Core/bin/Release/net472"
83+
}
84+
],
85+
"dest": "api"
86+
}
87+
],
88+
"build": {
89+
"template": ["default", "modern", "templates/material"],
90+
"globalMetadata": {
91+
"_appTitle": "AWS SDK for .NET API Reference",
92+
"_enableSearch": true
93+
}
94+
}
95+
}
96+
```
97+
98+
### Material Theme Customization
99+
100+
The Material theme can be customized by editing files in `templates/material/`:
101+
102+
- `public/main.css`: Main stylesheet for theme customization
103+
- `partials/`: Template partials for layout modifications
104+
- `styles/`: Additional styling options
105+
106+
Example color customization:
107+
```css
108+
[data-bs-theme='light'] nav.navbar {
109+
background-color: var(--bs-primary-bg-subtle);
110+
}
111+
```
112+
113+
## Architecture
114+
115+
### DocFX Integration Components
116+
117+
1. **DocFxIntegration.cs**: Main integration class handling DocFX operations
118+
2. **Updated SdkDocGenerator.cs**: Enhanced main generator with DocFX support
119+
3. **Configuration Files**: DocFX configuration and theme setup
120+
4. **Setup Scripts**: Automated setup and execution scripts
121+
122+
### Generation Process
123+
124+
When using DocFX mode (`-usedocfx`), the generator:
125+
126+
1. **Setup Phase**:
127+
- Downloads Material theme (if not present)
128+
- Updates DocFX configuration with current options
129+
130+
2. **Metadata Generation**:
131+
- Analyzes SDK assemblies using DocFX metadata generation
132+
- Creates YAML files with API documentation structure
133+
134+
3. **Build Phase**:
135+
- Builds documentation using DocFX with Material theme
136+
- Generates search index
137+
- Outputs final documentation site
138+
139+
### Legacy vs DocFX Mode
140+
141+
| Feature | Legacy Mode | DocFX Mode |
142+
|---------|-------------|------------|
143+
| Output Format | Custom HTML | Static site with modern UI |
144+
| Theme | Custom CSS | Material Design |
145+
| Search | Basic | Advanced with indexing |
146+
| Mobile Support | Limited | Fully responsive |
147+
| Performance | Slower | Optimized |
148+
| Maintenance | Custom code | Standard DocFX |
149+
150+
## Troubleshooting
151+
152+
### Common Issues
153+
154+
1. **DocFX not found**:
155+
```bash
156+
dotnet tool install -g docfx
157+
```
158+
159+
2. **Git not available**:
160+
- Install Git to enable Material theme download
161+
- Or manually download theme from: https://github.com/ovasquez/docfx-material
162+
163+
3. **Assembly not found errors**:
164+
- Ensure SDK is built: `dotnet build` in SDK root
165+
- Verify assemblies path with `-sdkassembliesroot`
166+
167+
4. **Permission errors**:
168+
- Ensure output directory is writable
169+
- Run with appropriate permissions
170+
171+
### Debugging
172+
173+
Enable verbose output for detailed information:
174+
```bash
175+
./SDKDocGenerator -usedocfx -verbose -testmode
176+
```
177+
178+
Check DocFX logs in the output directory for build-specific issues.
179+
180+
## Migration from Legacy Generator
181+
182+
To migrate from the legacy HTML generator:
183+
184+
1. **Install DocFX**: `dotnet tool install -g docfx`
185+
2. **Add DocFX flag**: Include `-usedocfx` in your build commands
186+
3. **Update scripts**: Modify existing build scripts to use new option
187+
4. **Test output**: Verify documentation generates correctly
188+
5. **Customize theme**: Adjust Material theme as needed
189+
190+
## Examples
191+
192+
### Basic Generation
193+
```bash
194+
# Generate docs for all services
195+
./SDKDocGenerator -usedocfx -sdkassembliesroot "/path/to/assemblies"
196+
```
197+
198+
### Test Mode
199+
```bash
200+
# Generate limited docs for testing
201+
./SDKDocGenerator -usedocfx -testmode -verbose
202+
```
203+
204+
### Specific Services
205+
```bash
206+
# Generate docs for specific services only
207+
./SDKDocGenerator -usedocfx -services "S3,DynamoDBv2,EC2" -verbose
208+
```
209+
210+
### Custom Output
211+
```bash
212+
# Generate to custom location
213+
./SDKDocGenerator -usedocfx -outputfolder "/custom/output/path" -clean
214+
```
215+
216+
## Contributing
217+
218+
When contributing to the DocFX integration:
219+
220+
1. **Test both modes**: Ensure legacy generator still works
221+
2. **Update documentation**: Keep this README current
222+
3. **Test themes**: Verify Material theme customizations
223+
4. **Performance**: Monitor generation time and output size
224+
225+
## Support
226+
227+
For issues specific to:
228+
- **DocFX**: See [DocFX documentation](https://dotnet.github.io/docfx/)
229+
- **Material Theme**: See [DocFX Material repository](https://github.com/ovasquez/docfx-material)
230+
- **AWS SDK**: Use standard AWS SDK support channels
231+

‎docgenerator/SDKDocGenerator/CommandLineParser.cs

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,13 @@ class ArgDeclaration
238238
HasValue = true,
239239
Parse = (arguments, argValue) => arguments.ParsedOptions.OutputFolder = argValue,
240240
HelpText = "The root folder beneath which the generated documentation will be placed."
241+
},
242+
new ArgDeclaration
243+
{
244+
OptionName = "usedocfx",
245+
ShortName = "docfx",
246+
Parse = (arguments, argValue) => arguments.ParsedOptions.UseDocFx = true,
247+
HelpText = "Use DocFX with Material theme instead of the legacy HTML generator for modern, beautiful documentation."
241248
}
242249
};
243250

0 commit comments

Comments
 (0)