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

Some improvements needed to vkconfig automatic layer setting doc generation? #1656

Open
KarenGhavam-lunarG opened this issue Feb 25, 2022 · 1 comment
Assignees
Labels
documentation OS - platform independent The issue doesn't depend on the OS Project - vkconfig Issues related to vkconfig

Comments

@KarenGhavam-lunarG
Copy link
Contributor

KarenGhavam-lunarG commented Feb 25, 2022

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:

gfxr_table

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:

gfxr_gen

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.

@bradgrantham-lunarg
Copy link
Contributor

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):
image

@christophe-lunarg christophe-lunarg self-assigned this Mar 5, 2024
@christophe-lunarg christophe-lunarg added Project - vkconfig Issues related to vkconfig documentation OS - platform independent The issue doesn't depend on the OS labels Mar 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation OS - platform independent The issue doesn't depend on the OS Project - vkconfig Issues related to vkconfig
Projects
None yet
Development

No branches or pull requests

3 participants