I have an idea to keep the markdown generated by TypeDoc in sync with the codebase changes.
- I am going to do a PR to add the
typedocscript to all our packages. As suggested by @juanma, I am going to export the markdown in a
tsdocfolder inside each package.
Once that is done, I am going to create two GitHub actions:
Check if TypeDoc is in sync: An action that runs all the
typedocscripts and fails if there are uncommitted files in git.
typedocscripts: An action that can be triggered by a comment (with the technique discovered by @mmczaplinski https://github.com/nwtgck/actions-comment-run) and runs the
typedocscripts and creates a new commit with the changes.
The main goal of using this vs a more automatic approach that generates new commits on each push is to try to keep the commit history clean of too many “Update typedocs” commits.
Thanks to the first action, we can make sure that we won’t merge a PR out of sync. Thanks to the second action, we don’t need to use the local repo to sync it.
Actually, it’s the very same workflow than the “Out of sync with
dev branch” that GitHub has, that doesn’t let you merge until you’ve merged the latest
dev changes, and there’s a button for doing that manually in the GitHub UI.
The normal workflow would be:
- Create PR…
- Work on your code…
- Once it’s ready for review, run
npm run typedoclocally to generate the markdown.
- (if you forget to run the command locally you can alternatively use the GH comment that runs the GH action that runs the script)
- Push everything. The GH action that checks that markdown is in sync should pass.
- Code reviewer can review the code.
- Doc reviewer can see the markdown changes of this PR and open the Doc PR.
- If changes are requested, owner will work on them and push the new code.
- If those changes made the markdown to be out of sync, the GH action will fail and won’t allow the merge.
- Once the changes are finished, the owner re-requests a review.
- Thanks to the GH action, owner and reviewers can see if the markdown is in sync or not. And thanks to the GH comment, they can just sync it again without needing to run the repo locally or ask the owner to do so.
Let me know what you think!