posit-dev / posit-dev/team-operator

Auto-generate typed config fields from product documentation

Open
#76 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Go
Stars
10
Forks
1
Avg merge
1d 8h
Merged PRs (30d)
4

Description

Summary

The operator now has a passthrough mechanism (#75) for arbitrary config values, but still only covers ~25-33% of each product's typed config fields. We should auto-generate these typed fields from the product documentation rather than maintaining them by hand.

Context

  • Connect has ~200+ config values, operator defines ~65
  • Package Manager has ~100+ config values, operator defines ~25
  • Both use gcfg format with well-structured documentation at docs.posit.co
  • The documentation HTML is consistently formatted and parseable (Section.Key headings with Type/Default metadata)
  • Workbench is deferred — multiple config files, scattered docs, passthrough-only for now

Work

  • Write a scraper/parser for the Connect and Package Manager configuration reference pages
  • Generate Go structs with appropriate types, json tags, kubebuilder validation markers, and doc comments
  • Define type mapping: doc types (string, boolean, integer, duration, byte-size, etc.) → Go types
  • Handle enums via kubebuilder validation markers
  • Output to connect_config_generated.go and package_manager_config_generated.go
  • Add CI job to detect drift between generated code and latest product docs
  • Determine whether generation runs at build-time or as a periodic sync workflow
  • Consider version tagging: generated code should record which product version it was generated from
  • Consider how dev/pre-release product versions interact with generated configs (passthrough covers the gap)

References

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Connect and Package Manager configuration reference pages and the passthrough work in PR #75. Design the scraper, type mapping, generated outputs connect_config_generated.go and package_manager_config_generated.go, and drift check around the documented HTML structure. Done means typed structs, validation markers, comments, version handling, and an agreed build-time or periodic generation workflow.

Written by the indexing model from the issue text.

Assessment

Tech stack
github-actions, go, kubernetes
Domain
build-system, devops
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.