GitHub user xuang7 created a discussion: Feedback on where to host the operator documentation generator
Hi everyone, as we are preparing the first version of the operator documentation, we would like to get feedback on where to host the scripts that generate it. **Background** The generator is fairly tightly coupled with the main repo's operator code. It relies on JVM reflection over operator classes, reads Jackson and schema-related annotations, uses runtime-generated JSON schema metadata such as propertyOrder, and directly depends on compiled operator classes on the classpath. We are currently considering two options: Option 1: Main repo (e.g. under /docs) - Pros - Shares the same sbt build as the operator classes, so reflection and schema generation work out of the box. - Easier for developers to regenerate docs. When adding or updating an operator, they can run the generator locally and inspect the resulting markdown immediately. - Cons - The generator and the published docs would live in different repos, so the generated markdown would still need to be synced to the site repo. Option 2: Texera site repo - Pros - Keeps the generator close to the Hugo config, theme, and layouts. - Keeps the main repo more focused on product code. - Cons - It would still need access to the compiled operator module, either through published artifacts or some way of repo linkage. - There is a higher risk of docs drifting out of sync with code. >From a quick look at projects such as Flink, Spark, and Airflow, the general >pattern seems to be that documentation is built close to the source code it >depends on, while the site repo mainly acts as a publishing target. That seems >more aligned with Option 1. Any feedback or alternative suggestions would be very welcome. Thanks. GitHub link: https://github.com/apache/texera/discussions/4380 ---- This is an automatically sent email for [email protected]. To unsubscribe, please send an email to: [email protected]
