Initial checkin
This commit is contained in:
Pim van Pelt
288
docs/DETAILS.md
Normal file
288
docs/DETAILS.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# s3-genindex - Detailed Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
s3-genindex is a Go rewrite of the original Python genindex.py script. It generates HTML directory listings with file type icons, responsive design, and dark mode support.
|
||||
|
||||
## Features
|
||||
|
||||
- **File Type Detection**: Recognizes 100+ file extensions with appropriate icons
|
||||
- **Responsive Design**: Works on desktop and mobile devices
|
||||
- **Dark Mode**: Automatic dark mode support based on system preferences
|
||||
- **Recursive Processing**: Generate indexes for entire directory trees
|
||||
- **File Filtering**: Include/exclude files by pattern or regex
|
||||
- **Symlink Support**: Special handling for symbolic links
|
||||
- **Custom Output**: Configurable output filename
|
||||
- **Breadcrumb Navigation**: Parent directory navigation
|
||||
|
||||
## Installation
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
git clone https://git.ipng.ch/ipng/s3-genindex.git
|
||||
cd s3-genindex
|
||||
make build
|
||||
```
|
||||
|
||||
### Using Go Install
|
||||
|
||||
```bash
|
||||
go install git.ipng.ch/ipng/s3-genindex/cmd/s3-genindex@latest
|
||||
```
|
||||
|
||||
## Command Line Options
|
||||
|
||||
```
|
||||
Usage: s3-genindex [OPTIONS] [directory]
|
||||
|
||||
-d, --dir-append append output file to directory href
|
||||
-f, --filter string only include files matching glob (default "*")
|
||||
-i, --include-hidden include dot hidden files
|
||||
-o, --output-file string custom output file (default "index.html")
|
||||
-r, --recursive recursively process nested dirs
|
||||
-v, --verbose verbosely list every processed file
|
||||
-x, --exclude-regex string exclude files matching regular expression
|
||||
--top-dir string top folder from which to start generating indexes
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Generate index.html in current directory
|
||||
s3-genindex
|
||||
|
||||
# Generate index for specific directory
|
||||
s3-genindex /path/to/directory
|
||||
|
||||
# Generate with custom output filename
|
||||
s3-genindex -o listing.html
|
||||
```
|
||||
|
||||
### Recursive Processing
|
||||
|
||||
```bash
|
||||
# Process directory tree recursively
|
||||
s3-genindex -r
|
||||
|
||||
# Process recursively with verbose output
|
||||
s3-genindex -rv /var/www
|
||||
```
|
||||
|
||||
### File Filtering
|
||||
|
||||
```bash
|
||||
# Include only Python files
|
||||
s3-genindex --filter "*.py"
|
||||
|
||||
# Exclude build artifacts and dependencies
|
||||
s3-genindex -x "(build|dist|node_modules|__pycache__|\\.tmp)"
|
||||
|
||||
# Include hidden files
|
||||
s3-genindex -i
|
||||
```
|
||||
|
||||
### Advanced Usage
|
||||
|
||||
```bash
|
||||
# Recursive with custom output and exclusions
|
||||
s3-genindex -r -o index.html -x "(\.git|\.svn|node_modules)" /var/www
|
||||
|
||||
# Verbose processing with directory appending
|
||||
s3-genindex -rv --dir-append /home/user/public
|
||||
```
|
||||
|
||||
## File Type Support
|
||||
|
||||
The tool recognizes and provides appropriate icons for:
|
||||
|
||||
### Programming Languages
|
||||
- Go (`.go`)
|
||||
- Python (`.py`, `.pyc`, `.pyo`)
|
||||
- JavaScript/TypeScript (`.js`, `.ts`, `.json`)
|
||||
- HTML/CSS (`.html`, `.htm`, `.css`, `.scss`)
|
||||
- Shell scripts (`.sh`, `.bash`, `.bat`, `.ps1`)
|
||||
- SQL (`.sql`)
|
||||
|
||||
### Documents
|
||||
- PDF (`.pdf`)
|
||||
- Text/Markdown (`.txt`, `.md`, `.markdown`)
|
||||
- Office documents (`.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`)
|
||||
- CSV (`.csv`)
|
||||
|
||||
### Media Files
|
||||
- Images (`.jpg`, `.png`, `.gif`, `.svg`, `.webp`)
|
||||
- Videos (`.mp4`, `.mov`, `.avi`, `.webm`)
|
||||
- Audio (`.mp3`, `.wav`, `.flac`, `.ogg`)
|
||||
|
||||
### Archives
|
||||
- Zip files (`.zip`, `.tar`, `.gz`, `.7z`, `.rar`)
|
||||
- Package files (`.deb`, `.rpm`, `.dmg`, `.pkg`)
|
||||
|
||||
### System Files
|
||||
- Certificates (`.crt`, `.pem`, `.key`)
|
||||
- Configuration files
|
||||
- License files (LICENSE, README)
|
||||
|
||||
## HTML Output Features
|
||||
|
||||
### Responsive Design
|
||||
- Mobile-friendly layout
|
||||
- Collapsible columns on small screens
|
||||
- Touch-friendly navigation
|
||||
|
||||
### Dark Mode
|
||||
- Automatic detection of system preference
|
||||
- Clean dark color scheme
|
||||
- Proper contrast ratios
|
||||
|
||||
### File Information
|
||||
- File sizes in human-readable format
|
||||
- Last modified timestamps
|
||||
- File type icons
|
||||
- Sorting (directories first, then alphabetical)
|
||||
|
||||
### Navigation
|
||||
- Parent directory links
|
||||
- Breadcrumb-style navigation
|
||||
- Clickable file/directory entries
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
s3-genindex/
|
||||
├── cmd/s3-genindex/ # Main application
|
||||
│ ├── main.go # CLI entry point
|
||||
│ └── main_test.go # CLI tests
|
||||
├── internal/indexgen/ # Core library
|
||||
│ ├── indexgen.go # Main functionality
|
||||
│ ├── indexgen_test.go # Unit tests
|
||||
│ └── integration_test.go # Integration tests
|
||||
├── docs/ # Documentation
|
||||
├── Makefile # Build automation
|
||||
├── README.md # Quick start guide
|
||||
└── go.mod # Go module definition
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
### Building
|
||||
|
||||
```bash
|
||||
make build # Build binary
|
||||
make test # Run tests
|
||||
make test-coverage # Run tests with coverage
|
||||
make check # Run all checks (fmt, vet, lint, test)
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
The project includes comprehensive tests:
|
||||
|
||||
- **Unit tests**: Test individual functions and utilities
|
||||
- **Integration tests**: Test complete directory processing workflows
|
||||
- **Template tests**: Verify HTML template generation
|
||||
- **CLI tests**: Test command-line argument parsing
|
||||
|
||||
Run tests with:
|
||||
|
||||
```bash
|
||||
make test # Basic test run
|
||||
make test-coverage # With coverage report
|
||||
go test -v ./... # Verbose output
|
||||
go test -short ./... # Skip integration tests
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
```bash
|
||||
make fmt # Format code
|
||||
make vet # Vet for issues
|
||||
make lint # Run golangci-lint (if installed)
|
||||
make check # Run all quality checks
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
No configuration files are needed. All options are provided via command-line arguments.
|
||||
|
||||
### Environment Variables
|
||||
|
||||
The tool respects standard Go environment variables:
|
||||
- `GOOS` and `GOARCH` for cross-compilation
|
||||
- `GOPATH` and `GOBIN` for installation paths
|
||||
|
||||
## Comparison with Original
|
||||
|
||||
This Go version provides the same functionality as the original Python script with these improvements:
|
||||
|
||||
### Performance
|
||||
- Faster execution, especially for large directory trees
|
||||
- Lower memory usage
|
||||
- Single binary deployment
|
||||
|
||||
### Maintenance
|
||||
- Comprehensive test suite
|
||||
- Type safety
|
||||
- Better error handling
|
||||
- Structured codebase
|
||||
|
||||
### Compatibility
|
||||
- Identical HTML output
|
||||
- Same command-line interface
|
||||
- Cross-platform binary
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Permission Errors**
|
||||
```bash
|
||||
# Ensure read permissions on target directory
|
||||
chmod +r /path/to/directory
|
||||
```
|
||||
|
||||
**Large Directories**
|
||||
```bash
|
||||
# Use verbose mode to monitor progress
|
||||
s3-genindex -v /large/directory
|
||||
|
||||
# Exclude unnecessary files
|
||||
s3-genindex -x "(\.git|node_modules|__pycache__)"
|
||||
```
|
||||
|
||||
**Memory Usage**
|
||||
```bash
|
||||
# Process directories individually for very large trees
|
||||
for dir in */; do s3-genindex "$dir"; done
|
||||
```
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable verbose output to see detailed processing:
|
||||
|
||||
```bash
|
||||
s3-genindex -v /path/to/debug
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
Licensed under the Apache License 2.0. See original Python script for full license text.
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Add tests for new functionality
|
||||
4. Run `make check` to ensure code quality
|
||||
5. Submit a pull request
|
||||
|
||||
## Changelog
|
||||
|
||||
### v1.0.0
|
||||
- Initial Go rewrite
|
||||
- Complete feature parity with Python version
|
||||
- Comprehensive test suite
|
||||
- Modern Go project structure
|
||||
Reference in New Issue
Block a user