Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add reference generator builds reference from the task graphs #63

Open
wants to merge 23 commits into
base: main
Choose a base branch
from

Conversation

kyasbal
Copy link
Member

@kyasbal kyasbal commented Feb 8, 2025

Add reference generator builds reference from the task graphs

Preview of the document:

https://github.com/GoogleCloudPlatform/khi/blob/3621de61e8a8a132fd3c6f701f2f0907e3c41017/docs/en/reference/inspection-type.md

Important

Making the whole this reference to a perfect document takes time especially if we care about every sentences of English.
Let's focus our reviews on the way of reference generation and the abstract structure of these reference regarding its template at this moment. And let's improve the content of them with another issue following this PR.

Overview

This PR adds document generator that create/update document markdowns generated from KHI source code.
KHI backend is built top of a DAG task runner system and each tasks have labels. This change make use of these to generate these documents from source code.

This change aims to achieve the following outcomes.

  • Reducing maintenance effort to keep codes and document latest
  • Testability over document. We can write tests to check documents without description or any important parameters.
  • Link from the frontend. We can generate anchor for headers automatically from values defined in the code base. It's easy to link these document from the corresponding UI element in future.

Amendable document auto generator

This PR utilizes the Golang package template/text with considering the usage for contributors to extend documents.
Generated text from templates consists of multiple section surrounded by:

<!-- BEGIN GENERATED PART: <ID of the generated section> -->
...(actual contents)
<!-- END GENERATED PART: <ID of the generated section> -->

Users can add texts after <!-- END GENERATED PART: <ID of the generated section> --> and the document generator keep the position sticked to the previous generated section.

This approach will generate the document with a bit noisy comments, but it enables humans to add contents directly on the document. KHI documents is expected to be hard if that was completely written only with texts, and several features have different points to pay attention. We needed the way to extend the automatically generated reference by human hand especially for adding screenshots, callouts or additional links ...etc.

@kyasbal kyasbal force-pushed the generate-document branch 2 times, most recently from 694c5d5 to 2e3f38e Compare February 8, 2025 15:21
@kyasbal kyasbal force-pushed the generate-document branch 11 times, most recently from 8dcccb0 to 785860a Compare February 10, 2025 10:13
@kyasbal kyasbal self-assigned this Feb 10, 2025
@kyasbal kyasbal marked this pull request as ready for review February 11, 2025 08:40
@kyasbal kyasbal requested review from RyuSA and jyane as code owners February 11, 2025 08:40
@kyasbal kyasbal changed the title [WIP]Adding document generator for tasks Adding document generator for tasks Feb 11, 2025
@kyasbal kyasbal changed the title Adding document generator for tasks Add reference generator build reference from the task graphs Feb 11, 2025
@kyasbal kyasbal changed the title Add reference generator build reference from the task graphs Add reference generator builds reference from the task graphs Feb 11, 2025
@kyasbal

This comment has been minimized.

@kyasbal kyasbal added the documentation Improvements or additions to documentation label Feb 15, 2025
@kyasbal
Copy link
Member Author

kyasbal commented Feb 20, 2025

@jyane Can we proceed review for this? At least for the document model part wound be better to have reviews, maybe?

@jyane
Copy link
Collaborator

jyane commented Feb 20, 2025

I'm extremely busy recently due to internal things, @RyuSA could you take a look?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Create a reference document for inspection types, timelines or feature tasks
2 participants