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

docs.rs should include array feature #228

Closed
msalib opened this issue Oct 18, 2021 · 3 comments · Fixed by #304
Closed

docs.rs should include array feature #228

msalib opened this issue Oct 18, 2021 · 3 comments · Fixed by #304
Assignees

Comments

@msalib
Copy link
Contributor

msalib commented Oct 18, 2021

It would be nice if we enabled at least the array feature for docs.rs by adding this to Cargo.toml:

[package.metadata.docs.rs]
features = ["array"]

Perhaps adding datetime to that list would be good as well.

The goal here is that someone looking at docs.rs should know that the array methods actually exist because otherwise, they're very easy to miss.

@michaelkirk
Copy link
Member

michaelkirk commented Oct 18, 2021

As a reference, the georust/proj crate does two things to document feature specific methods:

  1. enables features for the docs build (src):
[package.metadata.docs.rs]
features = [ "proj-sys/nobuild", "network", "geo-types" ]
rustdoc-args = ["--cfg", "docsrs"]
  1. annotates each feature gated function/object (src)...:
    #[cfg_attr(docsrs, doc(cfg(feature = "network")))]
    #[cfg(feature = "network")]
    pub fn enable_network(&self, enable: bool) -> Result<u8, ProjError> {
            // implementation ellided...
    }

...which then renders the feature requirement nicely on the generated proj docs like this:
Screen Shot 2021-10-18 at 1 47 18 PM

step 2 feels a little redundant to write, but I think it's really helpful for the doc consumers - otherwise they might wonder why they can't call the method that they see in the docs.

@ChristianBeilschmidt
Copy link
Contributor

I really like the idea and I also think we should add these cfg_attrs at the same time.

Maybe we can save some time in the realization if we decide on this first: #169
But nevertheless, it should be a manageable effort.

@jdroenner
Copy link
Member

the array feature is really just a conversion method from the Buffer to an ndarrray. Adding array to docs is a good idea.

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 a pull request may close this issue.

5 participants