Documentation
¶
Overview ¶
Package docs provides documentation generation from protobuf schemas.
Overview ¶
This package generates structured documentation from proto files, preserving comments and metadata, with support for multiple export formats (Markdown, HTML).
Documentation Structure ¶
Extracted Elements:
- Messages with fields and nested types
- Enums with values
- Services with RPC methods
- Field types and tags
- Deprecation markers
- Comments and descriptions
Usage Example ¶
Generate documentation:
generator := docs.NewGenerator() documentation := generator.Generate(protoAST)
Export to Markdown:
exporter := docs.NewMarkdownExporter() markdown := exporter.Export(documentation) // Save to README.md
Export to HTML:
exporter := docs.NewHTMLExporter(&docs.HTMLOptions{
Theme: "github",
IncludeTOC: true,
SyntaxHighlight: true,
})
html := exporter.Export(documentation)
Diff Support ¶
The pkg/docs/diff subpackage provides change documentation:
diff := diff.Compare(oldDoc, newDoc)
fmt.Printf("Added: %d, Removed: %d, Modified: %d\n",
diff.Added, diff.Removed, diff.Modified)
Related Packages ¶
- pkg/docs/diff: Documentation diffing
- pkg/docs/examples: Usage example generation
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DocsHandlers ¶
type DocsHandlers struct {
// contains filtered or unexported fields
}
DocsHandlers provides HTTP handlers for documentation
func NewDocsHandlers ¶
func NewDocsHandlers(storage api.Storage) *DocsHandlers
NewDocsHandlers creates new documentation handlers
func (*DocsHandlers) RegisterRoutes ¶
func (h *DocsHandlers) RegisterRoutes(router *mux.Router)
RegisterRoutes registers documentation routes
type Documentation ¶
type Documentation struct {
PackageName string
Syntax string
Description string
Messages []*MessageDoc
Enums []*EnumDoc
Services []*ServiceDoc
Imports []string
Options map[string]string
}
Documentation represents generated documentation for a proto schema
func (*Documentation) FindEnum ¶
func (d *Documentation) FindEnum(name string) *EnumDoc
FindEnum finds an enum by name
func (*Documentation) FindMessage ¶
func (d *Documentation) FindMessage(name string) *MessageDoc
FindMessage finds a message by name
func (*Documentation) FindService ¶
func (d *Documentation) FindService(name string) *ServiceDoc
FindService finds a service by name
func (*Documentation) Summary ¶
func (d *Documentation) Summary() string
Summary returns a summary of the documentation
type EnumDoc ¶
type EnumDoc struct {
Name string
FullName string
Description string
Values []*EnumValueDoc
Deprecated bool
}
EnumDoc represents documentation for an enum
type EnumValueDoc ¶
EnumValueDoc represents documentation for an enum value
type FieldDoc ¶
type FieldDoc struct {
Name string
Number int
Type string
Label string
Description string
Deprecated bool
Required bool
Optional bool
Repeated bool
OneofName string
}
FieldDoc represents documentation for a field
type Generator ¶
type Generator struct{}
Generator generates documentation from proto AST
func NewGenerator ¶
func NewGenerator() *Generator
NewGenerator creates a new documentation generator
type HTMLExporter ¶
type HTMLExporter struct {
// contains filtered or unexported fields
}
HTMLExporter exports documentation to HTML format
func NewHTMLExporter ¶
func NewHTMLExporter() *HTMLExporter
NewHTMLExporter creates a new HTML exporter
func (*HTMLExporter) Export ¶
func (e *HTMLExporter) Export(doc *Documentation) (string, error)
Export exports documentation to HTML
func (*HTMLExporter) ExportWithVersion ¶
func (e *HTMLExporter) ExportWithVersion(doc *Documentation, version string) (string, error)
ExportWithVersion exports documentation with version info
type MarkdownExporter ¶
type MarkdownExporter struct{}
MarkdownExporter exports documentation to Markdown format
func NewMarkdownExporter ¶
func NewMarkdownExporter() *MarkdownExporter
NewMarkdownExporter creates a new Markdown exporter
func (*MarkdownExporter) Export ¶
func (e *MarkdownExporter) Export(doc *Documentation) string
Export exports documentation to Markdown
func (*MarkdownExporter) ExportWithVersion ¶
func (e *MarkdownExporter) ExportWithVersion(doc *Documentation, version string) string
ExportWithVersion exports documentation with version information
type MessageDoc ¶
type MessageDoc struct {
Name string
FullName string
Description string
Fields []*FieldDoc
NestedTypes []*MessageDoc
Enums []*EnumDoc
Deprecated bool
Location string
}
MessageDoc represents documentation for a message
Source Files
Directories