Refactor documentation#2272
Conversation
jamietanna
left a comment
There was a problem hiding this comment.
If we're going to split the documentation across files, that's probably good - I've had grumblings in the past that GitHub's generated table of contents doesn't actually scroll so folks can't scroll through all the headers - but we should consider what this means for the docs in pkg.go.dev, which I believe only pull from README.md - do we need to make sure there's a subset of docs available for pkg.go.dev? Does docs/... work there?
I think if we're going to use Markdown-committed table of contents, we need a way to keep them up-to-date (via automation).
I guess you've generated them one-time using Claude, but to make it consistent, this needs to be automatable + validated in CI
Also, the reason for using an HTML table over Markdown is that it's easier to add new entries without worrying about formatting (should we be introducing whitespace to make sure all the Markdown table columns line up?) etc
(Haven't yet fully reviewed the different pages - will do shortly)
|
pkg.go.dev will only render a top level The HTML table was a workaround for markdown tables not supporting embedded preformatted blocks. I removed those, and replaced them with links to router-specific documentation, so it's not needed. Investigating table of contents automation right now, see if I can do something to make it easier, but there seems like no great way. |
|
Ok, I've automated the generation of the TOC. It has a rule in the makefile, and you can see the generated TOC surrounded by comment anchors to tell the tool where to place it. It's in the next commit. |
Added a way to automate generation of the table of contents.
Break up the README.md into smaller chunks, and add more docs about the configuration file. All the router examples and the config docs go into their own files under the docs/ directory.
Added a table of contents
For code review, it might be easier to peruse the docs in my source branch, rather than trying to understand it from diffs.