Documentation

[Fokko]

It would be great to have a minimal set of docs. I think we can get a lot of inspiration from the PyIceberg project where we use mkdocs: https://github.com/apache/iceberg-python/tree/main/mkdocs

We can copy the structure and the CI to deploy it.

With the CNAME file we can tell the ASF to set up a DNS entry to the docs. We could do https://rs.iceberg.apache.org/ or https://rust.iceberg.apache.org/, but I'll leave that up to the project.

[Xuanwo]

The name https://rust.iceberg.apache.org/ seems appropriate given that our repository is named iceberg-rust.

[liurenjie1024]

Just curious, what would be the relationship with docs of crates on docs.rs?

[liurenjie1024]

cc @Xuanwo

[Xuanwo]

Just curious, what would be the relationship with docs of crates on docs.rs?

From the ASF perspective, anything outside of apache.org does not exist. We should host our guide and API documentation on rust.iceberg.apache.org as the single source of truth. The documents on docs.rs are merely for the convenience of Rust users.

[liurenjie1024]

I took a look at py.iceerg.apache.org, it seems that the API and Code Reference sections should leave to docs.rs, while other parts should remain in website.

[Fokko]

I took a look at py.iceerg.apache.org, it seems that the API and Code Reference sections should leave to docs.rs, while other parts should remain in website.

I'm not super familiar with the Rust ecosystem, but I don't see any issues with having that on docs.rs. For other things, for example, how to contribute, how to release etc it would be best to keep that on the Apache side. It would also be great if we use mkdocs to make it easier to potentially merge the languages later on.

[liurenjie1024]

I'm not super familiar with the Rust ecosystem, but I don't see any issues with having that on docs.rs.

Just FYI, rust ecosystem has centralized online docs, here is just an example:

https://docs.rs/opendal/latest/opendal/

[Xuanwo]

I'm fine with not keeping a main branch for the API documentation. We can begin with the simplest approach and expand it later.

[liurenjie1024]

cc @Xuanwo Are you working on this? I think we are ok to ship the first release now, all blockers has been resolved.

[Xuanwo]

cc @Xuanwo Are you working on this? I think we are ok to ship the first release now, all blockers has been resolved.

I expect to finish it in next week.