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

ci: check Rust documentation #5056

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Conversation

arxanas
Copy link
Collaborator

@arxanas arxanas commented Dec 8, 2024

Follow-up from #5052. This isn't critical, so we can drop this PR if we think it's not important or not worth resolving the outstanding questions for now.

Questions:

  • What is our policy/strategy for new top-level checks vs embedding steps into existing checks?
    • I chose to make new top-level checks since I figured the feedback loop would be faster that way:
      • When a problem occurs, it's obvious at the top-level display that it's not a "real" test failure, just a rustdoc issue.
      • When you're fixing the problem, you don't have to wait the entire test suite.
    • However, it probably induces additional overall load to compile/process the codebase again?
  • What is our policy for setting the Rust toolchain for the new checks?
    • I chose MSRV for the doctests themselves, since I imagined that they could demonstrate the API boundary, which needs to adhere to MSRV.
      • See below: we don't have any "real" doctests right now. So it's mostly immaterial for now.
    • I chose stable for cargo doc in case new lints get added.
      • It could be annoying to have to resolve lints that don't appear unless you have the latest stable toolchain.
      • We're already doing this for cargo clippy, so I don't think it should be much worse than the status quo?

Notes:

  • These checks are mostly unrelated to the doc website generation.
  • We don't actually have any doctests at present.
  • I fixed the few existing rustdoc issues.
  • I highly recommend linking symbols in docs when possible (with square brackets, like [`Foo`]):
    • It makes the docs easier to navigate (both in the IDE and the crate documentation website).
    • With this PR, we can check validity of those references automatically to ensure the docs are up-to-date (via rustdoc::broken_intra_doc_links).
  • In the current setup, I added new non-required top-level checks.
    • They're not "required" checks unless/until somebody goes into the GitHub repo configuration and adds them.

Checklist

If applicable:

  • I have updated CHANGELOG.md
  • I have updated the documentation (README.md, docs/, demos/)
  • I have updated the config schema (cli/src/config-schema.json)
  • I have added tests to cover my changes

@arxanas arxanas force-pushed the arxanas/docs-2 branch 2 times, most recently from a51332e to 2065968 Compare December 8, 2024 20:29
@arxanas arxanas changed the title ci: check cargo doc ci: check Rust documentation Dec 8, 2024
@arxanas arxanas marked this pull request as ready for review December 8, 2024 21:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants