deploy docs on github pages

[zjp-CN]

This PR is very simple and may help to show docs under distinct and incompatible features, which is related to #36.

feature	deployed doc sample
use_tokio	https://zjp-cn.github.io/nvim-rs/use_tokio/nvim_rs
use_async-std	https://zjp-cn.github.io/nvim-rs/use_async-std/nvim_rs

Note:
This will create a gh-pages branch, and you have to set the source:

The generated files look like these.

---

Licensing: The code contributed to nvim-rs is licensed under the MIT or
Apache license as given in the project root directory.

[KillTheMule]

Hey thanks for the PR!

That seems like a feasible approach, but we don't need the "use_neovim_lib" feature, that's for testing/benchmarking only.

Is there a way to check that we're documenting all features this way? E.g. we might add "use_glib" in the future, could this workflow error out in that case, so we don't forget to add the docs?

[zjp-CN]

we don't need the "use_neovim_lib" feature

This is easy to remove it from .github/workflows/doc.sh.

Is there a way to check that we're documenting all features this way?

First, these is a way to warn/forbid all the missing docs on all public items and mods:

#![warn(missing_docs)]
#![deny(missing_docs)]

You can see rustdoc/lints.

Second, as for the feature or any cfg banners, you can use the unstable #![doc_auto_cfg] to auto add the banners (due to rust-lang/rust#89596 and rust-lang/rust#90502). Note this needs nightly Rust to get the documentation as expected. Here is a mini example:

# Cargo.toml
[features]
a = []
b = []

//! doc for crate

#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![warn(missing_docs)]

/// doc for feature a and unix
#[cfg(feature = "a")]
#[cfg(unix)]
pub mod a {}

/// doc for feature b
#[cfg(feature = "b")]
pub mod b {}

Run RUSTDOCFLAGS="--cfg docsrs" cargo doc --features a,b --no-deps to see

For nvim-rs, steps are:

1. use

#[cfg(feature = "use_tokio")] 

instead of

#[cfg(feature = "use_tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "use_tokio")))]

2. use

#![cfg_attr(docsrs, feature(doc_auto_cfg))]

instead of

#![cfg_attr(docsrs, feature(doc_cfg))]

[zjp-CN]

You can check the updated PR and sample documentation above.
Sorry for the duplicated commits, since I'm not familiar with git :)

[KillTheMule]

So, ok, I have those settings you showed above (many many thanks for the screenshot, I'd not have managed otherwise :D). Should work, shouldn't it?

[zjp-CN]

Oops two CI errors.
For Doc-Deploy error, personally I guess it's due to the GITHUB_TOKEN, because this kind of authentication has no permission to access to external repositories (due to lack of write permissions).
May using deploy_key be a better choice?

[KillTheMule]

I did those deploy_key things and retriggered the jobs. Not sure what this windows failure is about, though...

[KillTheMule]

The doc job still errors with the same error. I guess you'd need to do this: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-set-ssh-private-key-deploy_key?

[zjp-CN]

Yes, now I've replaced with GITHUB_TOKEN with the deploy_key.

[zjp-CN]

Seems I need to set that deploy_key too?

[zjp-CN]

Now I've set that ACTIONS_DEPLOY_KEY in the forked repo. Could you try again?

[zjp-CN]

I see what this means now:

deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}

You need a secret called ACTIONS_DEPLOY_KEY exactly in your repo setting.

Follow here :)

[KillTheMule]

Sorry I could not find time for the last few days :)

I've now redone the whole thing. The linked docs are outdated, but now I added ACTIONS_DEPLOY_KEY as an environment secrect for gh-pages, hopefully that works. Let's see!

(e) Naaa didn't work. I've added ACTIONS_DEPLOY_KEY as a repository secret. Maybe that works.

[KillTheMule]

No idea what to do now :( You can see what I did here, can you make heads or tails of this?

[zjp-CN]

Could you rerun the workflow again now? Because I added ACTIONS_DEPLOY_KEY as a repository secret just now.

[KillTheMule]

Just the same :(

[zjp-CN]

Well, failed again :(

[zjp-CN]

This time Doc CI is ignored due to the new commit :)
I've tested if some repo is owned by me with deploy-secret set like yours, everything is fine to go.
I noticed that a sentence lies on Action Secret web page:

Secrets are not passed to workflows that are triggered by a pull request from a fork.

So you can have this PR merged and then create a new commit on master branch to check whether the doc deployment is successful.

[KillTheMule]

So you can have this PR merged and then create a new commit on master branch to check whether the doc deployment is successful.

Alright, let's just try that!

[zjp-CN]

Cool, it works!
https://killthemule.github.io/nvim-rs/use_tokio/nvim_rs/
https://killthemule.github.io/nvim-rs/use_async-std/nvim_rs/

[KillTheMule]

Alright, nice, thanks for your patience.

Now I just need some sort of bannerpage on killthemule.github.io and proper links from the docs/README. And non-broken CI :D