Add action to check for and generate missing documentation #1728
Conversation
|
Just remember that those auto-generated drafts won't appear on the sidebar but will still be searchable. Sidebar auto-generation (which I've been talking about for months and it's still work-in-progress 😅) is based on folders. So eventually we would like to get something similar to 6.x docs arranged in folders. For now it is ok to have all markdown files in one folder, but I plan to change that at some point. |
Oh, that was not intentional at all - even though I modified the sidebar.js it didn't even occur to me to add these new files. Should I add these files? I think even just availability information being there is better than nothing. @KyrietS what are your thoughts? |
|
I think that these drafts should be listed in the sidebar so that users can see it and (hopefully) help us develop the documentation. I'm just wondering that maybe we should create a separate section in the sidebar for auto-generated pages to keep track of them 🤔. (And personally, I wouldn't bother to automate the process of adding these pages to the sidebar) Also, I think it would be nice if each draft had some sort of encouragement for the reader to help with the documentation improvements. "This page was auto-generated. Feel free to help us improve the documentation by creating a pull request." or something like that. |
samsinsane
force-pushed
the
ssurtees/docsCheck
branch
2 times, most recently
from
4c0c446
to
d8da037
Compare
|
@KyrietS I've added the encouragement as you requested, and I've (manually) added the new files to the sidebar. |
samsinsane
force-pushed
the
ssurtees/docsCheck
branch
2 times, most recently
from
4f83478
to
940f524
Compare
|
Looks like Docusaurus is complaining about |
|
@KyrietS I can just remove the commented out section for the files that I added, and just leave it in the template generation? |
|
@samsinsane Okay, then please do it. Their fix will be for the next version of Docusaurus anyway. |
samsinsane
force-pushed
the
ssurtees/docsCheck
branch
from
940f524
to
c5b29ff
Compare
|
@KyrietS I've removed the commented out section in the files this PR adds. Should be all good now! 😄 |
There was a problem hiding this comment.
Very cool. Couple of thoughts:
- Could we break this out to its own file under
scripts/and include it in, rather than embedding it inline intopremake5.lua? Seescripts/embed.luaas an example. I'd prefer to keep the main project file clean so it doesn't become overwhelming. - Is this something we want to keep around, or just run once & done? Ideally we wouldn't accept new PRs that don't include at least basic documentation for new code? I'm wondering if the PR should be just the placeholder pages for the missing APIs (as generated by this script), and then a CI check to fail if we find undocumented fields?
premake5.lua
Outdated
| local docfilepath = "website/docs/" .. k .. ".md" | ||
| local exists = os.isfile(docfilepath) | ||
| if not exists then | ||
| print("Genearting documenetation file for: ", k) |
There was a problem hiding this comment.
Typo, should be "Generating documentation file for:"
starkos
changed the title
There was a problem hiding this comment.
Agree with @starkos's comment. Other than that, I'm a happy camper. Huge thanks for doing this.
samsinsane
force-pushed
the
ssurtees/docsCheck
branch
from
c5b29ff
to
9ffaeea
Compare
samsinsane
force-pushed
the
ssurtees/docsCheck
branch
from
9ffaeea
to
dd5e812
Compare
- Added auto-generated documentation files for APIs without docs - Renamed editAndContinue.md to editandcontinue.md to match convention
samsinsane
force-pushed
the
ssurtees/docsCheck
branch
from
dd5e812
to
0fb9327
Compare
What does this PR do?
Adds a helpful action for the Premake project to auto-generate new documentation.
How does this PR change Premake's behavior?
Prevents CI builds from succeeding if documentation is missing.
Anything else we should know?
Under certain conditions the git commands won't work, for example if a user hasn't allowed tags to be downloaded. This PR doesn't necessarily focus on a single fix/feature as the template required for missing documentation needs to be reviewed. Similarly,
editAndContinueneeded to be corrected to avoid a false-positive on the missing documentation.Did you check all the boxes?
closes #XXXXin comment to auto-close issue when PR is merged)You can now support Premake on our OpenCollective. Your contributions help us spend more time responding to requests like these!