Enable building Rust API docs

[thunderbiscuit]

I'm not sure of the best way to do this, because we need the modules to be public for the docs to build correctly, but so far they've been private (you can't use the lib from another Rust project).

This is open mainly for discussion purposes. I could also just build locally and publish. See #941

Checklists

All Submissions:

• I've signed all my commits
• I followed the contribution guidelines
• I ran cargo fmt and cargo clippy before committing
• I've added a changelog in the next release tracking issue (see example)
• I've linked the relevant upstream docs or specs above

[thunderbiscuit]

Regarding using the --document-private-items flag:

This works, but has 2 downsides:

1. It adds a little lock icons to everything, which is IMO a bit confusing because if you know Rust docs you'd then think these are private APIs when in fact they are not.
2. It documents our actually private APIs, so now we expose more than we want to and is usable by users, leading to more confusion.

---

My feeling on this is that we're dealing with such a weird situation with uniffi and all, and the oddity of what it means to be public/private in this context (even worse the fact that uniffi completely disregards all of this), that I'm ok with a pretty unconventional approach. I suggest (for now at least, and we can switch when a better solution appears) that we could just build the docs locally (in a matter similar to how it's done in this PR) and push them to the GitHub pages for this repo. Nothing committed, no change in the public/private visibility modifiers. They cannot be hosted on the normally discoverable docs.rs website for Rust libraries, but honestly that's fine by me because they're not for Rust devs anyway (as is reflected by our policy on making all code in the lib private) and that was never my intention.

Edit: I have done just that and pushed to gh-pages to see how we feel about it. The site live at https://bitcoindevkit.github.io/bdk-ffi/bdkffi/index.html. One downside with it is that this approach cannot host many versions all at once, so only the latest version would be there (we could fix this with some custom landing page where you click on a button and it sends you to the correct website, all committed together, but maybe that's for another PR/discussion).

I think we could transform this PR into just adding a line in the docs/readme/release workflow maybe, that would remind the publishing dev to build and push whenever we push a tag.

[reez]

Yeah I agree with not using pub mod and with making Rust docs publishing a step in the release checklist.

[thunderbiscuit]

@reez ready for final review, let me know if this matches what you have in mind. Once it's in I'll run it for the 2.3.1 tag.

[reez]

👍

[reez]

a couple qs

[reez]

ok I think im on the same page with you, if This is open mainly for discussion purposes is still the case, I have 2 ideas Ill implement as slight alternatives to this

[reez]

ACK 4144aab