diff --git a/experimental/keptain/README.md b/experimental/keptain/README.md new file mode 100644 index 0000000..27a41ba --- /dev/null +++ b/experimental/keptain/README.md @@ -0,0 +1,22 @@ +Simple KEP explorer website. + +This is an experiment to see if we can make it easier for +maintainers to work with KEPs. + +It doesn't do much yet, it is mostly setting up a framework +for us to start to put value-add ideas. + +## Running + +First, you should check out the KEPs repo: + +``` +git clone https://github.com/kubernetes/enhancements.git +``` + +Then, you can run the website: +``` +go run . +``` + +Open your browser and go to [http://localhost:8080](http://localhost:8080) \ No newline at end of file diff --git a/experimental/keptain/design/README.md b/experimental/keptain/design/README.md new file mode 100644 index 0000000..a50e279 --- /dev/null +++ b/experimental/keptain/design/README.md @@ -0,0 +1,17 @@ +# Kubernetes KEP Explorer + +This website is a simple website that allows the user to explore kubernetes KEPs. + +We will start with basic "display" features, +and then add more features over time that streamline the KEP process, +for maintainers as well as for contributors. + +## Features + +### Basic Display Features + +We should be able to display a list of KEPs, +and for each KEP we have a landing page that displays the KEP content. + +Initially we link to the full KEP content from the landing page, +showing only keep metadata for each KEP. diff --git a/experimental/keptain/go.mod b/experimental/keptain/go.mod new file mode 100644 index 0000000..378c241 --- /dev/null +++ b/experimental/keptain/go.mod @@ -0,0 +1,13 @@ +module sigs.k8s.io/maintainers/experiments/keptain + +go 1.23 + +toolchain go1.23.5 + +require ( + github.com/yuin/goldmark v1.7.8 + k8s.io/klog/v2 v2.130.1 + sigs.k8s.io/yaml v1.4.0 +) + +require github.com/go-logr/logr v1.4.1 // indirect diff --git a/experimental/keptain/go.sum b/experimental/keptain/go.sum new file mode 100644 index 0000000..c86205b --- /dev/null +++ b/experimental/keptain/go.sum @@ -0,0 +1,12 @@ +github.com/go-logr/logr v1.4.1 h1:pKouT5E8xu9zeFC39JXRDukb6JFQPXM5p5I91188VAQ= +github.com/go-logr/logr v1.4.1/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= +github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38= +github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= +github.com/yuin/goldmark v1.7.8 h1:iERMLn0/QJeHFhxSt3p6PeN9mGnvIKSpG9YYorDMnic= +github.com/yuin/goldmark v1.7.8/go.mod h1:uzxRWxtg69N339t3louHJ7+O03ezfj6PlliRlaOzY1E= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +k8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk= +k8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE= +sigs.k8s.io/yaml v1.4.0 h1:Mk1wCc2gy/F0THH0TAp1QYyJNzRm2KCLy3o5ASXVI5E= +sigs.k8s.io/yaml v1.4.0/go.mod h1:Ejl7/uTz7PSA4eKMyQCUTnhZYNmLIl+5c2lQPGR2BPY= diff --git a/experimental/keptain/main.go b/experimental/keptain/main.go new file mode 100644 index 0000000..c8517f3 --- /dev/null +++ b/experimental/keptain/main.go @@ -0,0 +1,29 @@ +package main + +import ( + "context" + "fmt" + "os" + + "sigs.k8s.io/maintainers/experiments/keptain/pkg/store" + "sigs.k8s.io/maintainers/experiments/keptain/pkg/website" +) + +func main() { + if err := run(context.Background()); err != nil { + fmt.Fprintf(os.Stderr, "Error: %v\n", err) + os.Exit(1) + } +} + +func run(ctx context.Context) error { + // Initialize the KEP repository + kepRepo, err := store.NewRepository("enhancements") + if err != nil { + return fmt.Errorf("error creating KEP repository: %w", err) + } + + // Start the web server + server := website.NewServer(kepRepo) + return server.Run(":8080") +} diff --git a/experimental/keptain/pkg/model/kep.go b/experimental/keptain/pkg/model/kep.go new file mode 100644 index 0000000..03754d5 --- /dev/null +++ b/experimental/keptain/pkg/model/kep.go @@ -0,0 +1,25 @@ +package model + +// KEP represents a Kubernetes Enhancement Proposal +type KEP struct { + // Path is the path to the KEP file, relative to the repo base + Path string `json:"path"` + + // Title is the title of the KEP + Title string `json:"title"` + + // Number is the number of the KEP + Number string `json:"number"` + + // Authors are the authors of the KEP + Authors []string `json:"authors"` + + // Status is the status of the KEP + Status string `json:"status"` + + // TextURL is the URL to the KEP README.md file + TextURL string `json:"textURL"` + + // TextContents is the contents of the KEP README.md file + TextContents string `json:"-"` +} diff --git a/experimental/keptain/pkg/store/kep.go b/experimental/keptain/pkg/store/kep.go new file mode 100644 index 0000000..e12c521 --- /dev/null +++ b/experimental/keptain/pkg/store/kep.go @@ -0,0 +1,172 @@ +package store + +import ( + "fmt" + "os" + "path/filepath" + "strings" + + "sigs.k8s.io/maintainers/experiments/keptain/pkg/model" + "sigs.k8s.io/yaml" +) + +// Repository represents a KEP repository +type Repository struct { + basePath string + keps map[string]*model.KEP +} + +// NewRepository creates a new KEP repository instance +func NewRepository(basePath string) (*Repository, error) { + r := &Repository{ + basePath: basePath, + keps: make(map[string]*model.KEP), + } + if err := r.loadKEPs(); err != nil { + return nil, fmt.Errorf("error loading KEPs: %v", err) + } + return r, nil +} + +func (r *Repository) loadKEPs() error { + // Walk the KEPs directory and load all KEPs + if err := filepath.Walk(r.basePath, func(path string, info os.FileInfo, err error) error { + if err != nil { + return err + } + if info.IsDir() { + return nil + } + + // We assume there's a metadata file for each KEP called kep.yaml + if filepath.Base(path) != "kep.yaml" { + return nil + } + + relativePath, err := filepath.Rel(r.basePath, path) + if err != nil { + return fmt.Errorf("error getting relative path: %w", err) + } + + dir := filepath.Dir(path) + relativeDir := filepath.Dir(relativePath) + + b, err := os.ReadFile(path) + if err != nil { + return fmt.Errorf("error reading KEP file: %w", err) + } + kep, err := r.parseKEPFile(b) + if err != nil { + // Log error but continue processing other KEPs + return fmt.Errorf("error parsing KEP %q: %w", path, err) + } + + // use the (repo-relative) directory as the identifier for the KEP + kep.Path = relativeDir + + // See if we have a README.md file + { + readme := filepath.Join(dir, "README.md") + readmeBytes, err := os.ReadFile(readme) + if err != nil { + if !os.IsNotExist(err) { + return fmt.Errorf("error getting README.md: %w", err) + } + return nil + } + + if err == nil { + kep.TextContents = string(readmeBytes) + kep.TextURL = fmt.Sprintf("https://github.com/kubernetes/enhancements/blob/master/%s", filepath.Join(relativeDir, "README.md")) + } + } + r.keps[kep.Path] = kep + return nil + }); err != nil { + return fmt.Errorf("error walking KEPs: %w", err) + } + + return nil +} + +// ListKEPs returns all KEPs in the repository +// If query is provided, it will filter the KEPs based on the query +func (r *Repository) ListKEPs(query string) ([]*model.KEP, error) { + var ret []*model.KEP + for _, kep := range r.keps { + // Filter KEPs if search query is provided + match := true + if query != "" { + query = strings.ToLower(query) + if strings.Contains(strings.ToLower(kep.Title), query) || + strings.Contains(strings.ToLower(kep.Number), query) || + containsAuthor(kep.Authors, query) { + match = true + } + } + + if match { + ret = append(ret, kep) + } + } + return ret, nil +} + +func containsAuthor(authors []string, query string) bool { + for _, author := range authors { + if strings.Contains(strings.ToLower(author), query) { + return true + } + } + return false +} + +// GetKEP returns a specific KEP by number +func (r *Repository) GetKEP(path string) (*model.KEP, error) { + kep, ok := r.keps[path] + if ok { + return kep, nil + } + return nil, fmt.Errorf("KEP %s not found", path) +} + +// kepFile is the format used in the KEP file. +type kepFile struct { + Title string `json:"title"` + Number string `json:"kep-number"` + Authors []string `json:"authors"` + OwningSig string `json:"owning-sig"` + ParticipatingSigs []string `json:"participating-sigs"` + Reviewers []string `json:"reviewers"` + Approvers []string `json:"approvers"` + Editor string `json:"editor"` + CreationDate string `json:"creation-date"` + LastUpdated string `json:"last-updated"` + Status string `json:"status"` + SeeAlso []string `json:"see-also"` + Replaces []string `json:"replaces"` + SupersededBy []string `json:"superseded-by"` +} + +// parseKEPFile parses a KEP yaml file +func (r *Repository) parseKEPFile(data []byte) (*model.KEP, error) { + + var kep kepFile + if err := yaml.Unmarshal(data, &kep); err != nil { + return nil, fmt.Errorf("error parsing KEP yaml: %v", err) + } + + // Extract additional metadata from the yaml + var rawMap map[string]interface{} + if err := yaml.Unmarshal(data, &rawMap); err != nil { + return nil, fmt.Errorf("error parsing KEP metadata: %v", err) + } + + out := &model.KEP{ + Title: kep.Title, + Number: kep.Number, + Authors: kep.Authors, + Status: kep.Status, + } + return out, nil +} diff --git a/experimental/keptain/pkg/website/server.go b/experimental/keptain/pkg/website/server.go new file mode 100644 index 0000000..26ff1f7 --- /dev/null +++ b/experimental/keptain/pkg/website/server.go @@ -0,0 +1,163 @@ +package website + +import ( + "bytes" + "fmt" + "html/template" + "net/http" + + "github.com/yuin/goldmark" + "github.com/yuin/goldmark/extension" + "github.com/yuin/goldmark/parser" + "github.com/yuin/goldmark/renderer/html" + "github.com/yuin/goldmark/text" + "k8s.io/klog/v2" + "sigs.k8s.io/maintainers/experiments/keptain/pkg/model" + "sigs.k8s.io/maintainers/experiments/keptain/pkg/store" +) + +// Server is the main HTTP server for the website +type Server struct { + kepRepo *store.Repository +} + +// NewServer creates a new Server +func NewServer(kepRepo *store.Repository) *Server { + return &Server{kepRepo: kepRepo} +} + +// Run starts the server, and listens on the given endpoint forever. +func (s *Server) Run(endpoint string) error { + mux := http.NewServeMux() + + // Serve static files + fs := http.FileServer(http.Dir("static")) + mux.Handle("GET /static/", http.StripPrefix("/static/", fs)) + + // Routes + mux.HandleFunc("GET /", s.handleHome) + mux.HandleFunc("GET /api/search", s.handleSearch) + mux.HandleFunc("GET /kep/{path...}", s.handleKEP) + + fmt.Println("Server starting on :8080...") + return http.ListenAndServe(endpoint, mux) +} + +// HomePageData is the data model for the home page +type HomePageData struct { + AllWorkflows []*model.KEP + Query string +} + +// handleHome handles the home page, which is the list of all KEPs +func (s *Server) handleHome(w http.ResponseWriter, r *http.Request) { + ctx := r.Context() + log := klog.FromContext(ctx) + + query := r.URL.Query().Get("q") + log.Info("Listing all workflows", "query", query) + + keps, err := s.kepRepo.ListKEPs(query) + if err != nil { + http.Error(w, fmt.Sprintf("Error loading KEPs: %v", err), http.StatusInternalServerError) + return + } + + data := HomePageData{ + AllWorkflows: keps, + Query: query, + } + + tmpl := template.Must(template.ParseFiles("templates/home.html")) + if err := tmpl.Execute(w, data); err != nil { + http.Error(w, fmt.Sprintf("Error rendering template: %v", err), http.StatusInternalServerError) + } +} + +// handleSearch handles the search fragment on the homepage, used when typing into the list. +// We may be able to harmonize this with handleHome in future. +func (s *Server) handleSearch(w http.ResponseWriter, r *http.Request) { + ctx := r.Context() + log := klog.FromContext(ctx) + + query := r.URL.Query().Get("q") + log.Info("Searching KEPs", "query", query) + + keps, err := s.kepRepo.ListKEPs(query) + if err != nil { + http.Error(w, fmt.Sprintf("Error loading KEPs: %v", err), http.StatusInternalServerError) + return + } + + data := HomePageData{ + AllWorkflows: keps, + Query: query, + } + + tmpl := template.Must(template.ParseFiles("templates/home.html")) + if err := tmpl.ExecuteTemplate(w, "kep_list", data); err != nil { + http.Error(w, fmt.Sprintf("Error rendering template: %v", err), http.StatusInternalServerError) + } +} + +// KEPPageData is the data model for the KEP "detail" page +type KEPPageData struct { + Workflow *model.KEP + ContentHTML template.HTML +} + +// handleKEP handles the KEP "detail" page, which is the page that displays the KEP content. +func (s *Server) handleKEP(w http.ResponseWriter, r *http.Request) { + ctx := r.Context() + log := klog.FromContext(ctx) + + path := r.PathValue("path") + + log.Info("Listing KEP", "path", path) + + kep, err := s.kepRepo.GetKEP(path) + if err != nil { + http.Error(w, fmt.Sprintf("Error loading KEP: %v", err), http.StatusNotFound) + return + } + + // Idea: Maybe we should pre-render the markdown to HTML in the store, + // and just serve the HTML here? + + // Configure markdown processor with GitHub Flavored Markdown + md := goldmark.New( + goldmark.WithExtensions( + extension.GFM, + extension.Typographer, + extension.Table, + ), + goldmark.WithParserOptions( + parser.WithAutoHeadingID(), + ), + goldmark.WithRendererOptions( + html.WithUnsafe(), // Required for GFM tables and task lists + html.WithXHTML(), + ), + ) + + // Create a new parser context with TOC enabled + context := parser.NewContext() + + // Parse the markdown content + var buf bytes.Buffer + doc := md.Parser().Parse(text.NewReader([]byte(kep.TextContents)), parser.WithContext(context)) + if err := md.Renderer().Render(&buf, []byte(kep.TextContents), doc); err != nil { + http.Error(w, fmt.Sprintf("Error converting markdown: %v", err), http.StatusInternalServerError) + return + } + + data := KEPPageData{ + Workflow: kep, + ContentHTML: template.HTML(buf.String()), + } + + tmpl := template.Must(template.ParseFiles("templates/kep.html")) + if err := tmpl.Execute(w, data); err != nil { + http.Error(w, fmt.Sprintf("Error rendering template: %v", err), http.StatusInternalServerError) + } +} diff --git a/experimental/keptain/static/css/style.css b/experimental/keptain/static/css/style.css new file mode 100644 index 0000000..2f1a5ce --- /dev/null +++ b/experimental/keptain/static/css/style.css @@ -0,0 +1,351 @@ +:root { + --primary-color: #326ce5; + --background-color: #f5f7fa; + --text-color: #2c3e50; + --card-background: #ffffff; +} + +* { + margin: 0; + padding: 0; + box-sizing: border-box; +} + +body { + font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif; + line-height: 1.6; + color: var(--text-color); + background-color: var(--background-color); +} + +header { + background-color: var(--primary-color); + color: white; + padding: 1rem 2rem; + box-shadow: 0 2px 4px rgba(0,0,0,0.1); +} + +header h1 { + margin: 0; +} + +header nav { + margin-top: 1rem; +} + +header nav a { + color: white; + text-decoration: none; +} + +main { + max-width: 1200px; + margin: 2rem auto; + padding: 0 1rem; +} + +.kep-list { + display: grid; + grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); + gap: 1.5rem; +} + +.kep-card { + background-color: var(--card-background); + border-radius: 8px; + padding: 1.5rem; + box-shadow: 0 2px 4px rgba(0,0,0,0.1); + transition: transform 0.2s ease; +} + +.kep-card:hover { + transform: translateY(-2px); +} + +.kep-card h2 { + margin-bottom: 1rem; + color: var(--primary-color); +} + +.kep-card a { + color: inherit; + text-decoration: none; +} + +.kep-detail { + background-color: var(--background-color); + border-radius: 8px; + padding: 0.5rem; +} + +.kep-detail h1 { + color: var(--primary-color); + margin-bottom: 1.5rem; +} + +.kep-metadata { + background-color: var(--card-background); + border-radius: 8px; + padding: 1.5rem; + color: #666; + box-shadow: 0 2px 4px rgba(0,0,0,0.1); + margin-bottom: 2rem; +} + +.kep-metadata p { + margin: 0.5rem 0; +} + +.kep-metadata strong { + color: #24292e; +} + +.kep-content { + background-color: var(--card-background); + border-radius: 8px; + padding: 1.25rem; + box-shadow: 0 2px 4px rgba(0,0,0,0.1); +} + +dl { + display: grid; + grid-template-columns: auto 1fr; + gap: 0.5rem 1rem; + margin-top: 1rem; +} + +dt { + font-weight: bold; +} + +footer { + text-align: center; + padding: 2rem; + color: #666; + border-top: 1px solid #ddd; +} + +.search-container { + max-width: 800px; + margin: 20px auto; + padding: 0 20px; + position: relative; +} + +.search-container input[type="text"] { + width: 100%; + padding: 12px 20px; + font-size: 16px; + border: 2px solid #ddd; + border-radius: 6px; + transition: border-color 0.2s ease; +} + +.search-container input[type="text"]:focus { + outline: none; + border-color: var(--primary-color); +} + +.search-status { + margin-top: 8px; + color: #666; + font-size: 14px; + text-align: right; +} + +.search-container button { + padding: 10px 20px; + background-color: #326ce5; + color: white; + border: none; + border-radius: 4px; + cursor: pointer; + font-size: 16px; +} + +.search-container button:hover { + background-color: #2857b8; +} + +.htmx-indicator { + display: none; + position: absolute; + right: 30px; + top: 50%; + transform: translateY(-50%); + width: 20px; + height: 20px; + border: 3px solid #f3f3f3; + border-top: 3px solid var(--primary-color); + border-radius: 50%; + animation: spin 1s linear infinite; +} + +@keyframes spin { + 0% { transform: translateY(-50%) rotate(0deg); } + 100% { transform: translateY(-50%) rotate(360deg); } +} + +.htmx-request .htmx-indicator { + display: block; +} + +.htmx-request.htmx-indicator { + display: block; +} + +/* + * Try to style our markdown content to render similar to how Github renders it. + * (Because this is the renderer we've used when creating most of the KEPs) +*/ +.markdown-body { + font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif; + font-size: 16px; + line-height: 1.5; + word-wrap: break-word; + color: #24292e; +} + +.markdown-body h1, +.markdown-body h2, +.markdown-body h3, +.markdown-body h4, +.markdown-body h5, +.markdown-body h6 { + margin-top: 24px; + margin-bottom: 16px; + font-weight: 600; + line-height: 1.25; +} + +.markdown-body h1 { + font-size: 2em; + padding-bottom: 0.3em; + border-bottom: 1px solid #eaecef; +} + +.markdown-body h2 { + font-size: 1.5em; + padding-bottom: 0.3em; + border-bottom: 1px solid #eaecef; +} + +.markdown-body h3 { + font-size: 1.25em; +} + +.markdown-body h4 { + font-size: 1em; +} + +.markdown-body p { + margin-top: 0; + margin-bottom: 16px; +} + +.markdown-body ul, +.markdown-body ol { + margin-top: 0; + margin-bottom: 16px; + padding-left: 2em; +} + +.markdown-body ul ul, +.markdown-body ul ol, +.markdown-body ol ol, +.markdown-body ol ul { + margin-top: 0; + margin-bottom: 0; +} + +.markdown-body li { + word-wrap: break-all; +} + +.markdown-body li + li { + margin-top: 0.25em; +} + +.markdown-body code { + padding: 0.2em 0.4em; + margin: 0; + font-size: 85%; + background-color: rgba(27,31,35,0.05); + border-radius: 3px; + font-family: SFMono-Regular, Consolas, "Liberation Mono", Menlo, monospace; +} + +.markdown-body pre { + padding: 16px; + overflow: auto; + font-size: 85%; + line-height: 1.45; + background-color: #f6f8fa; + border-radius: 3px; + margin-bottom: 16px; +} + +.markdown-body pre code { + padding: 0; + margin: 0; + font-size: 100%; + word-break: normal; + white-space: pre; + background: transparent; + border: 0; +} + +.markdown-body blockquote { + padding: 0 1em; + color: #6a737d; + border-left: 0.25em solid #dfe2e5; + margin: 0 0 16px 0; +} + +.markdown-body table { + display: block; + width: 100%; + overflow: auto; + margin-top: 0; + margin-bottom: 16px; + border-spacing: 0; + border-collapse: collapse; +} + +.markdown-body table th, +.markdown-body table td { + padding: 6px 13px; + border: 1px solid #dfe2e5; +} + +.markdown-body table tr { + background-color: #fff; + border-top: 1px solid #c6cbd1; +} + +.markdown-body table tr:nth-child(2n) { + background-color: #f6f8fa; +} + +.markdown-body img { + max-width: 100%; + box-sizing: content-box; + background-color: #fff; +} + +.markdown-body hr { + height: 0.25em; + padding: 0; + margin: 24px 0; + background-color: #e1e4e8; + border: 0; +} + +.markdown-body a { + color: #0366d6; + text-decoration: none; +} + +.markdown-body a:hover { + text-decoration: underline; +} \ No newline at end of file diff --git a/experimental/keptain/templates/home.html b/experimental/keptain/templates/home.html new file mode 100644 index 0000000..06b4ae4 --- /dev/null +++ b/experimental/keptain/templates/home.html @@ -0,0 +1,48 @@ + + + + + + Kubernetes KEP Explorer + + + + +
+

Kubernetes KEP Explorer

+
+
+
+ +
+
+
+
+ {{template "kep_list" .}} +
+
+ + + + +{{define "kep_list"}} + {{range .AllWorkflows}} +
+

{{.Title}}

+
+

KEP Number: {{.Number}}

+

Status: {{.Status}}

+

Authors: {{range .Authors}}{{.}} {{end}}

+
+
+ {{end}} +{{end}} \ No newline at end of file diff --git a/experimental/keptain/templates/kep.html b/experimental/keptain/templates/kep.html new file mode 100644 index 0000000..b9b632b --- /dev/null +++ b/experimental/keptain/templates/kep.html @@ -0,0 +1,35 @@ + + + + + + {{.Workflow.Title}} - Kubernetes KEP Explorer + + + +
+

Kubernetes KEP Explorer

+ +
+
+
+

{{.Workflow.Title}}

+ + +
+ {{.ContentHTML}} +
+
+
+ + + \ No newline at end of file