Rust: documentation and release pipelines

[WardBrian]

Follow on from #105

• Add a rust page under docs/languages (just a link to docs.rs page? make sure we have a back link, too)
• Add a new heading in CONTRIBUTING.md describing the Rust build/dependencies.
• Add github action to publish on release (crates.io API token is under secret CRATES_TOKEN)

[WardBrian]

@aseyboldt if you have any free time to spare, I'd love to get the remaining Rust issues finished so we can have a release with the Rust client in it

[aseyboldt]

Sorry @WardBrian for not getting back to this sooner, I still had a couple of other things I needed to catch up on.
I'll add the language docs (that would probably mostly be a link to crates.io I think? Anything in the readme will be shown in the API docs, and it will be tested automatically...) and see if I can figure out the publish action...

[aseyboldt]

Looks like you beat me to it :-)
Do you think anything else is still missing?

[aseyboldt]

About Rng and Send + Sync: I could be missing something, but I think they actually are Send and Sync. I don't think they contain any thread locals or so, do they? And I don't think there is any interior mutability either, as all functions that modify an rng take a mut reference.
It is not allowed to use the same rng instance for a call into bridgestan at the same time from different threads, but if those functions take mut references to the rng, that can't happen anyway, because there can never be two mut references to the same thing.

[WardBrian]

those functions take mut references to the rng, that can't happen anyway

Ah fair enough, I hadn't considered that the only places you can use them require exclusivity anyway.

In terms of remaining steps:
The doc comments for functions are a bit all over the place - some list out the formal arguments, some just give a one-sentence description, etc. From looking around at some other crates, it seems like the standard practice is pretty terse descriptions rather than describing each argument in detail, but it would be worth doing a pass over all of them to make sure they're both correct and internally consistent

[aseyboldt]

I expanded some of the docs a bit, and made the argument description more consistent: https://github.com/aseyboldt/bridgestan/tree/rust-doc-improvements

[WardBrian]

Thanks for that @aseyboldt. I will try to do a once-over on everything this week and merge this.

[aseyboldt]

I guess I need to enable a spell checker in my code editor :-)

[WardBrian]

I think this is ready to go, I'd appreciate if both @aseyboldt and @roualdes could review the text before merging.

I checked the output locally using cargo package and it looks good, so I am hopeful the cargo publish part of the next release will go smoothly. If it fails for any reason we can do it manually and then debug.

[aseyboldt]

You need an unsafe function to register a printing function, but I think that's probably not worth mentioning here, given that that's a pretty specialized use-case?

[WardBrian]

Yes, I think that's the exception rather than the rule

[roualdes]

This looks good. Thanks to you both for putting in so much work on the Rust interface and the associated doc.

I'm marking request changes, solely based on the file extension in the link to the Rust example, not related to anything below this.

And maybe this is even a separate issue altogether, but I'm having with the tests. There are 4 failures on my machine after I run cargo test and 9 tests passed. Here are the 4 failures

failures:
create_all_late_drop_fwd
create_all_parallel
create_all_serial
create_all_thread_serial

I also can't get the example to run. Though this is probably just my lack of Rust knowledge.

[WardBrian]

@roualdes what failures are you getting from those tests?

We should probably provide the command to run the example somewhere, it is:

cargo run --example=example

[roualdes]

+1 to us including the cargo command to run the Rust example, even if the set of users who want to run the Rust example but know little about Rust is probably small.

I re-compiled all the test models with STAN_THREADS=true and all the errors I saw went away. So maybe we should say this somewhere too? Though I guess we don't for the Julia tests, which have the same requirement.

Without STAN_THREADS=true both the Rust tests and the example failed with messages about a thread panicking.

[WardBrian]

The thread safety guarantees the Rust interface gives (via the Rust type system) require STAN_THREADS. There should be a nice runtime message about this, but typing this out also makes me realize this is needs to be much more documented in the documentation for this interface

[aseyboldt]

Good catch.
I pushed a commit with some docs about this here: https://github.com/aseyboldt/bridgestan/tree/rust-doc-improvements (same location as last commit).

[roualdes]

@aseyboldt those additions look great. Thanks for adding them. Will you merge your edits into this branch so we can accept this PR?

Separately, we probably want a similar set of sentences for Julia. I'll open a new issue.

[roualdes]

Looks great. Thanks!

[WardBrian]

@aseyboldt - can you imagine anything else to be done for Rust before we push a release? Otherwise I think we will try to do that today or tomorrow so that you can add a dependency in nuts-rs/nutpie

[aseyboldt]

@WardBrian Can't think of anything missing.
Would we great to see this released, a nutpie release will then follow pretty quickly. :-)