docgen/website: show deprecated function warnings on docs website#584
docgen/website: show deprecated function warnings on docs website#584cpu merged 12 commits intorustls:mainfrom
Conversation
Maybe we should start checking in the data JSON and set up CI to verify that a fresh That way we could review the JSON diffs alongside code updates (both to the tool & the lib) to see if we accidentally lose items/comments/etc. |
|
Thanks for the review 🌠 I'll iterate this weekend. |
cpu
force-pushed
the
ci/cpu-deprecate-notes
branch
from
746a69e to
968640d
Compare
djc
left a comment
djc
left a comment
There was a problem hiding this comment.
Sorry for all the nitty feedback...
Will try to return to this soon. The weather has been too nice to spend weekends indoors 😆 |
cpu
force-pushed
the
ci/cpu-deprecate-notes
branch
from
968640d to
f349f0d
Compare
cpu
force-pushed
the
ci/cpu-deprecate-notes
branch
from
f349f0d to
87643b4
Compare
This way we can review updates to the website documentation data
alongside code changes.
```
$ cargo run --manifest-path tools/Cargo.toml --bin docgen > ./website/static/api.json
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.06s
Running `target/debug/docgen`
```
Now that we're checking in the `api.json` content generated by the `docgen` tool the expectation is that there shouldn't be any uncommitted diffs when running the tool fresh in CI.
But update the package/upload and deploy steps to only happen for rustls-ffi's main branch.
Also rename some bindings for clarity. The input node is the previous sibling node for a to-be-documented item so call it `prev`. We also look at `prev`'s previous sibling node, so call those instances `prev_prev`.
We also only care about named (not anonymous) sibling nodes, so use just `prev_named_sibling()` instead of the mix of `prev_sibling()` and `prev_named_sibling()`.
Handle the simple case up-front.
We can handle the case where prev is an expression_statement by recursing with `prev_prev`.
The `api.json` data is updated to add the newly parsed deprecation messages.
cpu
force-pushed
the
ci/cpu-deprecate-notes
branch
from
87643b4 to
4f1a848
Compare
|
@djc I think this is hopefully ready for one final review. Sorry it's been a slog. |
djc
left a comment
djc
left a comment
There was a problem hiding this comment.
Skimmed this, LGTM! Thanks for the iterations...
2 participants
Updates the
docgentool from thetoolscrate to parse theDEPRECATED_FUNCmacro invocations ahead of function declarations. Once parsed we can pull out the argument message and include that in the JSON data generated by the tool.With the deprecated messages the
websiteZola templates can reference them to add a note of the deprecation in the TOC and to add a warning banner to the item's docs rendering.Resolves #582
Examples: