geo

geo copied to clipboard

Is this possible with docs.rs? For example, we can't currently see the Transform algorithm on docs.rs/geo

https://docs.rs/about/metadata

all-features = true?

Yeah, that seems right to me. The main thing is whether there's a way to build the proj feature flag on the docs.rs builders

I'm not sure; proj has some specific settings for docs.rs because you can't build non-Rust dependencies from source: https://github.com/georust/proj/blob/main/Cargo.toml#L37-L39 but I don't know how that will interact with cargo when called by geo …

I also don't think there's a way to test what happens without pushing a release, which isn't ideal for our dependents.

It is possible to build your crate docs locally using the docs.rs environment: https://github.com/rust-lang/docs.rs#pure-docker-compose, but it's not particularly forthcoming...

I'm giving it a go. It'd be great to see Transform and stuff on docs.rs.

Could we use the CI Docker image as the base? Since it already has Rust and PROJ, if I recall correctly

We could use that, but I don't understand what we'd gain.

My understanding is we're trying to make sure that whatever changes we ultimately publish will work in the docs.rs environment.

Ah, my understanding was the challenge with publishing to docs.rs is that the docs.rs environment doesn't have PROJ installed. Ignore me if I'm just getting in the way 🐢

To explain a little better what I was thinking:

the challenge with publishing to docs.rs is that the docs.rs environment doesn't have PROJ

Yeah, I think that's correct. But there are a couple of options that come to mind to address it:

1. We have successfully generated docs for the proj crate at https://docs.rs/proj. To do that, we sort of "fake it" when we detect we're being built on docs.rs and don't look for the actual libproj library. Maybe we can do something like that for geo - like maybe just passing the proj/no_build feature.

2. We could install proj on docs.rs: https://github.com/rust-lang/crates-build-env 🙀

Either of these things I think will require a little trial and error. Our current mechanism for doing that is to "do it live!" (publish a release and see what happens on docs.rs). That's not a very fast feedback cycle, nor would all these trial-and-error releases be very nice to our users.

So my thinking was to set up the docs.rs env locally, and see what I can get to work, which is where I'm at now.

So, our local dev-dependencies, like geo-test-fixtures seems to confuse the local docker-compose run of docs.rs. Commenting them out in Cargo.toml seems to run the build. I don't think this is an issue as the actual docs.rs build has been working.

To include proj, adding this in geo/Cargo.toml this seems to work:

[dependencies]
proj-sys = { version = "*", optional = true }

[package.metadata.docs.rs]
rustdoc-args = ["--cfg", "docsrs"]
features = ["use-proj", "use-serde", "proj-sys/nobuild"]

I'm guessing that should document the proj support in geo?