Skip to content

Proposal: Restructure DataFusion site #1821

Closed

Description

@matthewmturner

Is your feature request related to a problem or challenge? Please describe what you are trying to do.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
(This section helps Arrow developers understand the context and why for this feature, in addition to the what)

I am proposing to restructure the DataFusion site drawing some inspiration from the Arrow site (https://arrow.apache.org/docs). Assuming we reach consensus on some variant of this I think this issue would be best served as a parent / tracker since completing this will have many changes.

Describe the solution you'd like
A clear and concise description of what you want to happen.

I think it would be nice if the structure was something like the below. This is very rough right now (and im not familiar enough with the complete installation to fill in all details) but I think illustrates an overall structure that would be nice - IMHO.

  • About
    • Quarterly Roadmap
    • Long Term Roadmap
  • Supported Environments
    • Rust
      • Installation
      • Key Interfaces
        • ExecutionContext
        • DataFrame
        • ObjectStore
        • ListingTable
        • ...
      • Internals # I figure since Rust is the foundation for everything else its worth explaining some of the internals???
        • Logical Plan
        • Physical Plan
        • Expressions
        • ...
      • Extensions
      • API Reference
      • ...
    • Python
      • Installation
      • API Reference
      • ...
    • Java???
    • CLI
      • Installation
      • ...
    • Ballista
      • Installation
      • ...
  • Cookbook
    • Rust
    • Python
    • CLI
    • Ballista
  • Development
    • Rust
    • Python
    • CLI
    • Ballista
  • Specification
    • DataFusion's invariants
    • DataFusions output field name semantics
    • SQL Reference
  • Community
    • Communication
    • Issue tracker
    • Code of conduct
    • DataFusion-contrib
    • FAQ

I personally really like having Cookbooks to learn the idiomatic / performant ways to perform various tasks (see https://arrow.apache.org/cookbook/py/ as an example). That being said I recognize it would be extra work and likely isnt needed in the short run until the core structure is in place. But in the medium to longer term I think there is real value in it - in particular for new users.

Similar can be said for the Internals section in rust. That being said, I believe @alamb and @andygrove have already produced some presentations / talks that could potentially be leveraged to help fill in those details (on top of whatever is in docs.rs).

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

I have a few datafusion features I plan on working on in the short-medium term but after those are completed i would be happy to drive the implementation of this once there is agreement.

Activity

  1. matthewmturner commented on Feb 13, 2022

    @matthewmturner
    ContributorAuthor

    This is still rough, but I've been reviewing the site and wanted to get down in writing some of my ideas. I dont think any of this would make the 7.0 release but let me know if anyone thinks otherwise.

    FYI - and interested in your thoughts @alamb @houqp @andygrove @jimexist @Dandandan @xudong963

  2. changed the title [-]Proposal: Restrucutre DataFusion site[/-] [+]Proposal: Restructure DataFusion site[/+] on Feb 14, 2022
  3. alamb commented on Feb 14, 2022

    @alamb
    Contributor

    In general, I like this idea / organization a lot. Thank you for writing it down @matthewmturner

    My biggest piece of feedback / request for any reorganization is to ensure we keep the following content clearly delinated:

    1. Content for those who want to use DataFusion in their project (examples, cookbook, etc)
    2. Content for those who want to develop DataFusion

    In particular I think it is very important not to mix the developer documentation with the user documentation

    That being said, I also think the SQL reference / feature list (being targeted towards users) might be good to feature in a more prominent section (alongside Rust)

    I personally really like having Cookbooks to learn the idiomatic / performant ways to perform various tasks (see https://arrow.apache.org/cookbook/py/ as an example). That being said I recognize it would be extra work and likely isnt needed in the short run until the core structure is in place. But in the medium to longer term I think there is real value in it - in particular for new users.

    I agree -- one thing I think we could do is to make the existing "examples" more discoverable (you basically now have to check out the code and know where to look): https://github.com/apache/arrow-datafusion/tree/master/datafusion-examples/examples . There are a lot of good examples there.

    Similar can be said for the Internals section in rust. That being said, I believe @alamb and @andygrove have already produced some presentations / talks that could potentially be leveraged to help fill in those details (on top of whatever is in docs.rs).

    👍

  4. xudong963 commented on Feb 14, 2022

    @xudong963
    Member

    Thanks @matthewmturner, make sense to me!

  5. alamb commented on Dec 20, 2024

    @alamb
    Contributor

    I think the current site, while not quite the proposal of @matthewmturner is much better than when this ticket was written

    https://datafusion.apache.org/

    Thus let's close this one to clean up the backlog:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions