Check docs in CI

[fedgiac]

Make it so that the docs build and keep doing so without warnings.

More precisely:

• Fixing all doc issues accumulated so far.
• New just commands, doc-devs and doc, to generate respectively the dev docs (with aggressive linting) and public docs.
• New CI step checking the docs.

Context

During an unrelated task, I've noticed that Claude encountered some issues when generating the docs.
Building the crate docs emitted rustdoc warnings, but nothing caught them: just lint runs clippy (which doesn't touch rustdoc lints) and CI never built the docs at all. I want the docs to build cleanly and to stay that way.

just doc-check is appended to just all (at the end), and a new docs job in .github/workflows/ci.yml runs it on every push/PR.

Both doc recipes use --no-deps. This is because it makes both commands much faster: documenting the full dependency tree costs minutes in exchange for clickable external-type links in the full docs: nice but not worth the extra minutes imho. doc-dev additionally passes --document-private-items so it also checks internal docs; doc leaves them out so the browsable output is a clean public view. Warnings are passed as errors in the check only.

Generating and viewing the docs

Run just doc: it builds all workspace crates' docs.
You can pass in extra parameters, this is specifically intended to make it easier open the browser: just doc --open. See relevant just syntax docs here.
The generated HTML lives under target/doc/.

If you're running in a VM, you can serve the content, port-forward and take a look at them with your browser:

python3 -m http.server -d target/doc

Click on the folder of each crate to see the docs (e.g., http://localhost:8000/settlement_interface/).

Doc build timings

Benchmark on my VM with:

cargo clean --doc
s=$SECONDS; <command>; echo "$((SECONDS - s))s"

--no-deps	just doc	just doc-dev
kept	2s	1s
dropped	281s	210s

A note on check-only mode

Ideally we'd have a recipe just for validating the docs without writing any HTML, but rustdoc's --check mode is gated behind -Z unstable-options (nightly).

Testing

• just doc-dev passes with zero warnings (previously 8).
• just doc generates the docs.
• just all runs the full sweep including the new doc-check at the end.
• CI output.

[kaze-cow]

just minor things

Run just doc: it builds all workspace crates' docs and opens them in your browser. The generated HTML lives under target/doc/.

For me it didn't actually open my browser. I had to add --open to the underlying cargo doc command in order to do that. Maybe make it possible to specify additional varaidic arguments through Just?

Then, serve the content, for example:

Serving with a HTTP server really isn't necessary, can be loaded with command like

open target/doc/settlement_interface/index.html

[kaze-cow]

this is less of a "doc-check" and more of a "doc-fullsince it primarily adds the private docs and makes warnings a failure. This means that the CI could end up having errors even if a dev just usedcargo doc` on their local machine

Maybe it would be best to just stick with one doc just command (the current doc-check)

If we do want to have a separate doc command for expected later public consumption, then maybe we should have just doc-prod or just doc-release

[fedgiac]

Fair point. I still like the split and I think doc should still generate the main docs. What do you think about 63eb741 (basically keeping docs and renaming the check to doc-dev)?

[fedgiac]

For me it didn't actually open my browser. I had to add --open to the underlying cargo doc command in order to do that.
Maybe make it possible to specify additional varaidic arguments through Just?

Whoops. At first I added --open, then I decided it isn't really helpful and dropped it, but didn't update the PR (it is now). Also, I work from a VM so no browser opens for me, I can't really test it. 😁
Anyway, I liked the suggestion so I implemented it, now it's possible to do just doc --open.

[kaze-cow]

all comments addressed