feat(ui): add relationship management features in schema editor
- Implement functionality to create, update, delete, and view relationships between tables. - Introduce new UI screens for managing relationships, including forms for adding and editing relationships. - Enhance table editor with navigation to relationship management. - Ensure relationships are displayed in a structured table format for better usability.
This commit is contained in:
196
GODOC.md
Normal file
196
GODOC.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# RelSpec API Documentation (godoc)
|
||||
|
||||
This document explains how to access and use the RelSpec API documentation.
|
||||
|
||||
## Viewing Documentation Locally
|
||||
|
||||
### Using `go doc` Command Line
|
||||
|
||||
View package documentation:
|
||||
```bash
|
||||
# Main package overview
|
||||
go doc
|
||||
|
||||
# Specific package
|
||||
go doc ./pkg/models
|
||||
go doc ./pkg/readers
|
||||
go doc ./pkg/writers
|
||||
go doc ./pkg/ui
|
||||
|
||||
# Specific type or function
|
||||
go doc ./pkg/models Database
|
||||
go doc ./pkg/readers Reader
|
||||
go doc ./pkg/writers Writer
|
||||
```
|
||||
|
||||
View all documentation for a package:
|
||||
```bash
|
||||
go doc -all ./pkg/models
|
||||
go doc -all ./pkg/readers
|
||||
go doc -all ./pkg/writers
|
||||
```
|
||||
|
||||
### Using `godoc` Web Server
|
||||
|
||||
**Quick Start (Recommended):**
|
||||
```bash
|
||||
make godoc
|
||||
```
|
||||
|
||||
This will automatically install godoc if needed and start the server on port 6060.
|
||||
|
||||
**Manual Installation:**
|
||||
```bash
|
||||
go install golang.org/x/tools/cmd/godoc@latest
|
||||
godoc -http=:6060
|
||||
```
|
||||
|
||||
Then open your browser to:
|
||||
```
|
||||
http://localhost:6060/pkg/git.warky.dev/wdevs/relspecgo/
|
||||
```
|
||||
|
||||
## Package Documentation
|
||||
|
||||
### Core Packages
|
||||
|
||||
- **`pkg/models`** - Core data structures (Database, Schema, Table, Column, etc.)
|
||||
- **`pkg/readers`** - Input format readers (dbml, pgsql, gorm, prisma, etc.)
|
||||
- **`pkg/writers`** - Output format writers (dbml, pgsql, gorm, prisma, etc.)
|
||||
|
||||
### Utility Packages
|
||||
|
||||
- **`pkg/diff`** - Schema comparison and difference detection
|
||||
- **`pkg/merge`** - Schema merging utilities
|
||||
- **`pkg/transform`** - Validation and normalization
|
||||
- **`pkg/ui`** - Interactive terminal UI for schema editing
|
||||
|
||||
### Support Packages
|
||||
|
||||
- **`pkg/pgsql`** - PostgreSQL-specific utilities
|
||||
- **`pkg/inspector`** - Database introspection capabilities
|
||||
- **`pkg/reflectutil`** - Reflection utilities for Go code analysis
|
||||
- **`pkg/commontypes`** - Shared type definitions
|
||||
|
||||
### Reader Implementations
|
||||
|
||||
Each reader is in its own subpackage under `pkg/readers/`:
|
||||
|
||||
- `pkg/readers/dbml` - DBML format reader
|
||||
- `pkg/readers/dctx` - DCTX format reader
|
||||
- `pkg/readers/drawdb` - DrawDB JSON reader
|
||||
- `pkg/readers/graphql` - GraphQL schema reader
|
||||
- `pkg/readers/json` - JSON schema reader
|
||||
- `pkg/readers/yaml` - YAML schema reader
|
||||
- `pkg/readers/gorm` - Go GORM models reader
|
||||
- `pkg/readers/bun` - Go Bun models reader
|
||||
- `pkg/readers/drizzle` - TypeScript Drizzle ORM reader
|
||||
- `pkg/readers/prisma` - Prisma schema reader
|
||||
- `pkg/readers/typeorm` - TypeScript TypeORM reader
|
||||
- `pkg/readers/pgsql` - PostgreSQL database reader
|
||||
- `pkg/readers/sqlite` - SQLite database reader
|
||||
|
||||
### Writer Implementations
|
||||
|
||||
Each writer is in its own subpackage under `pkg/writers/`:
|
||||
|
||||
- `pkg/writers/dbml` - DBML format writer
|
||||
- `pkg/writers/dctx` - DCTX format writer
|
||||
- `pkg/writers/drawdb` - DrawDB JSON writer
|
||||
- `pkg/writers/graphql` - GraphQL schema writer
|
||||
- `pkg/writers/json` - JSON schema writer
|
||||
- `pkg/writers/yaml` - YAML schema writer
|
||||
- `pkg/writers/gorm` - Go GORM models writer
|
||||
- `pkg/writers/bun` - Go Bun models writer
|
||||
- `pkg/writers/drizzle` - TypeScript Drizzle ORM writer
|
||||
- `pkg/writers/prisma` - Prisma schema writer
|
||||
- `pkg/writers/typeorm` - TypeScript TypeORM writer
|
||||
- `pkg/writers/pgsql` - PostgreSQL SQL writer
|
||||
- `pkg/writers/sqlite` - SQLite SQL writer
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Reading a Schema
|
||||
|
||||
```go
|
||||
import (
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/readers/dbml"
|
||||
)
|
||||
|
||||
reader := dbml.NewReader(&readers.ReaderOptions{
|
||||
FilePath: "schema.dbml",
|
||||
})
|
||||
db, err := reader.ReadDatabase()
|
||||
```
|
||||
|
||||
### Writing a Schema
|
||||
|
||||
```go
|
||||
import (
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/writers"
|
||||
"git.warky.dev/wdevs/relspecgo/pkg/writers/gorm"
|
||||
)
|
||||
|
||||
writer := gorm.NewWriter(&writers.WriterOptions{
|
||||
OutputPath: "./models",
|
||||
PackageName: "models",
|
||||
})
|
||||
err := writer.WriteDatabase(db)
|
||||
```
|
||||
|
||||
### Comparing Schemas
|
||||
|
||||
```go
|
||||
import "git.warky.dev/wdevs/relspecgo/pkg/diff"
|
||||
|
||||
result := diff.CompareDatabases(sourceDB, targetDB)
|
||||
err := diff.FormatDiff(result, diff.OutputFormatText, os.Stdout)
|
||||
```
|
||||
|
||||
### Merging Schemas
|
||||
|
||||
```go
|
||||
import "git.warky.dev/wdevs/relspecgo/pkg/merge"
|
||||
|
||||
result := merge.MergeDatabases(targetDB, sourceDB, nil)
|
||||
fmt.Printf("Added %d tables\n", result.TablesAdded)
|
||||
```
|
||||
|
||||
## Documentation Standards
|
||||
|
||||
All public APIs follow Go documentation conventions:
|
||||
|
||||
- Package documentation in `doc.go` files
|
||||
- Type, function, and method comments start with the item name
|
||||
- Examples where applicable
|
||||
- Clear description of parameters and return values
|
||||
- Usage notes and caveats where relevant
|
||||
|
||||
## Generating Documentation
|
||||
|
||||
To regenerate documentation after code changes:
|
||||
|
||||
```bash
|
||||
# Verify documentation builds correctly
|
||||
go doc -all ./pkg/... > /dev/null
|
||||
|
||||
# Check for undocumented exports
|
||||
go vet ./...
|
||||
```
|
||||
|
||||
## Contributing Documentation
|
||||
|
||||
When adding new packages or exported items:
|
||||
|
||||
1. Add package documentation in a `doc.go` file
|
||||
2. Document all exported types, functions, and methods
|
||||
3. Include usage examples for complex APIs
|
||||
4. Follow Go documentation style guide
|
||||
5. Verify with `go doc` before committing
|
||||
|
||||
## References
|
||||
|
||||
- [Go Documentation Guide](https://go.dev/doc/comment)
|
||||
- [Effective Go - Commentary](https://go.dev/doc/effective_go#commentary)
|
||||
- [godoc Documentation](https://pkg.go.dev/golang.org/x/tools/cmd/godoc)
|
||||
Reference in New Issue
Block a user