Add doc generation script with doc templates #49
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
templates/template_vars.yaml
Outdated
| README: | ||
| filename: README.md | ||
| template: genai-perf-templates/README_template | ||
| release: 24.08 |
There was a problem hiding this comment.
Great work!
Is there a way to centralize the variables here? It seems like this moves us from needing to find the variables to update to being able to update them in one file then run the script. The next step for me would be to just having one centralized list of variables (maybe in this file?) to then know we need to update each one once. We'd go to the top of the and update release version, CLI version, etc. once and be done.
There was a problem hiding this comment.
This was a conscientious decision on my part to provide flexibility for every file while still centralizing all variables.
I can see going forward making a central list and then only overwrite if it is specified for a file. However, I did not want to over engineer this right now when ops is likely to take this completely out of this repo.
I wanted a short term solution that had room to evolve for later.
For now, search and replace in this one file is still very straight forward.
There was a problem hiding this comment.
Yeah I had the same suggestion. I had your branch pulled and was working on it when the suggestion came through. Seems like it's not as straight-forward as I'd hoped, though I'm no YML expert. I think we can extend this in the future.
There was a problem hiding this comment.
Updated the script to centralize the variables to a single general set.
Now each file may specialize a variable which will take precedence over the general variable if both are defined.
Thank you for the suggestion, @dyastremsky and @fpetrini15!
|
Great work @debermudez! In my testing, many of the files are unchanged because there is no version to modify. I'm assuming you expected this and are just generating templates in advance? Would it be better to only add template files as needed to reduce bloat? |
That is expected behavior yes. Most of the docs are not going to need updates. |
debermudez
force-pushed
the
dbermudez-automate-doc-updates
branch
from
0cd74d6 to
1f9c6b0
Compare
* Add doc generation script with doc templates * Set autoescape to True to avoid XSS attacks * Further centralize template vars to 1 entry with the ability to specialize * Add ability to run script from the root dir
Trying to centralize the doc maintenance.
Now there is a perf_analyzer/templates directory. In that directory exists template_vars.yaml, generate_docs.py, and a directory of genai-perf jinja2 templates for the docs.
All of the templates are in normal markdown except where a release number or variable that needs to be updated exists. When you run generate_docs.py in the templates directory, the script will iterate over the files in the template_vars.yaml file, populating all fields in the template with the respective value in the yaml file.
Finally, the generated docs are written out to their current location to avoid manual copying.
Now, instead of scouring the codebase for release values to update every month, we can update 1 file and regenerate the docs. Only the docs that change need to be committed.
The next step is to expand this to perf_analyzer's docs where this is even more helpful.