Fix docs.rs build

[metasim]

The docs.rs build is failing due to PDAL not being available in the documentation environment.

Advice has been requested from the cxx community to determine what the best path forward is.

Notes

See also: https://docs.rs/about/builds

Building in docs.rs environment

1. git clone https://github.com/rust-lang/docs.rs.git
2. cd docs.rs
3. Edit docker-compose.yaml and add a volume mount to your package (figuratively):
   services.web.volumes[-1]: "/my/source/pdal:/opt/docsrs/pdal:ro"
4. docker-compose up -d db s3
5. Run build: docker-compose run web build crate --local /opt/docsrs/pdal
6. View build: cargo run -- start-web-server

[urschrei]

What we did for proj and proj-sys was:

1. Generate the -sys docs manually (if you need them), since libproj doesn't update often. We then copy the generated docs into https://github.com/georust/proj/blob/main/proj-sys/src. This needs some config in lib.rs
2. Add a nobuild feature to build.rs for proj-sys and enable it for docs.rs: https://github.com/georust/proj/blob/main/proj-sys/Cargo.toml. This skips the build script, allowing the docs.rs build to continue.
3. Ensure that the nobuild feature is enabled in proj: https://github.com/georust/proj/blob/main/Cargo.toml

More hints here: rust-lang/docs.rs#147 (comment)

[metasim]

Thanks for the tips @urschrei!! 🙏

[metasim]

@urschrei Followup, just in case you might know: I'm using cxx (not bindgen) where Rust code is generated with a proc-macro. I don't guess you've seen that incorporated into this pattern?