LunarG
Some improvements needed to vkconfig automatic layer setting doc generation?
When we were moving all of the layers to automatically have their layer settings documentation automatically generated, there were some concerns about the readability of the automatically generated documentation from the GFXReconstruct repository. So we delayed moving the GFXReconstruct repository to using the automatic layer setting documentation approach until this issue could be resolved. @bradgrantham-lunarg please add any additional information to this issue that you may have.
Some examples of the concerns:
The generated documentation is not as clear as the hand-written table that's there now.
Table that was in the USAGE markdown:
It's clear what the environment variable value is, it's clear what the description is, and the alternating white/gray rows separate the options well.
What it will be when generated:
It's harder to figure out which is which, "Capture Specific Frames" (the setting) is not very different from "Setting Properties" (a header every setting has). I feel like this is just a word waterfall that has to be parsed for the meaning. "Setting Default Value" is on the same line as "Setting Type". The "Setting Properties" aren't split or aligned like a table so my eye has to search for the bits.
I investigated this a little and there doesn't appear to be a portable Github-Flavored Markdown way to have a table without a header. Having to have a header makes a per-setting repeated Setting Properties table awkward. Here's the best I have so far:
## Setting Properties
| Property | Value(s) |
| - | - |
| vk_layer_settings.txt Variable | "lunarg_gfxreconstruct.capture_file" |
| Environment Variable | "`GFXRECON_CAPTURE_FILE`" |
| Platforms | WINDOWS, LINUX, ANDROID |
| Setting Type | `SAVE_FILE` |
| Setting Default Value | "gfxrecon_capture.gfxr" |
And that ends up looking like (in Typora):
