ongchi opened a new issue, #9173: URL: https://github.com/apache/arrow-datafusion/issues/9173
### Is your feature request related to a problem or challenge? There are currently two documentation hosting targets for DataFusion: [docs.rs](https://docs.rs/) (several crates) and [arrow.apache.org](https://arrow.apache.org/datafusion). 1. **docs.rs** - All crates published to [crates.io](https://crates.io) are automatically documented on [docs.rs](https://docs.rs/). Doc tests can also serve as working examples and ensure the correctness of documentation. 2. **User Guide** - The document hosted on [arrow.apache.org](https://arrow.apache.org/datafusion) is generated by Sphinx with manually mantained document source. It's a great source for getting an overview of the project and understanding how DataFusion works and its general usage. Parts of the documentation could be shared between each other. For example, [built-in functions](https://docs.rs/datafusion-expr/35.0.0/datafusion_expr/expr_fn/index.html) should also be listed in the [Expression API](https://arrow.apache.org/datafusion/user-guide/expressions.html#) of the user guide. However, each of them maintain its own document source separately, and they are not fully consistant with each other. ### Describe the solution you'd like Merge relevant parts of Sphinx source into Rust doc comments. Then extract doc comments from JSON output ([rfcs#2963](https://rust-lang.github.io/rfcs/2963-rustdoc-json.html#unresolved-questions) - nightly toolchain required) of the `rustdoc` and generate markdown files. Finally, include these files in Sphinx by `doctree`. A utility to generate markdown files from doc comments is required. It should not take much effort by utilizing [rustdoc-json](https://docs.rs/rustdoc-json/latest/rustdoc_json/index.html) and [rustdoc-types](https://docs.rs/rustdoc-types/latest/rustdoc_types/index.html). ### Describe alternatives you've considered Create a shared doc folder between Rust and Sphinx source, and merge relevant part into one. Then include external file by doc attribute in Rust, or by `doctree` in Sphinx. **This is really annoying to find the right file when writing doc in development. And I don't want to do that.🤪** ### Additional context _No response_ -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
