Skip to content

no longer build the left nav for class members #3018

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from

Conversation

devoncarew
Copy link
Member

This PR modies the class member pages (constructors, methods, properties) so that they no longer have a class member nav in the left-hand side area. My guess is that people are not using that area to navigate around the class - that the use the class page for that, click on a member to examine it more closely, and then navigate back to the class page for any other investigation.

Not having navs at this level gives us some significant size improvements - it knocks some of the ~ quadratic growth off the generated docs (proportional to the number of library or class symbols) . Some stats from building the flutter docs:

With member left-hand side navs (before this change):

  • 1,898.9 sec to generate (~31.6 mins)
  • generated doc size: 9.29 GB

Without member left-hand side navs (after this change):

  • 1,777.6 sec to generate (~29.6 mins)
  • generated doc size: 891.8 MB

Starting as a draft PR as I'm having some trouble testing this locally - I want to see how this does on the CI.

@srawlins
Copy link
Member

This is a very very visible, very large change to the UI. Do we need some UX opinions here, or comparisons with other API docs?

This does alleviate the quadratic concern; we have other ideas for solving that so I don't want to hurt UX to solve something that will be solved soon in another way.

@devoncarew
Copy link
Member Author

This is a very very visible, very large change to the UI. Do we need some UX opinions here, or comparisons with other API docs?

I'll add some screenshots to this PR (in a bit) to help us think about the change.

This does alleviate the quadratic concern; we have other ideas for solving that so I don't want to hurt UX to solve something that will be solved soon in another way.

I think we still have issues here for libraries that have a lot of top level symbols (lots of classes, lots of library fields, ...). Agree that there are other ways to address this (near term, having a script build the nav in the page; longer term, re-doing the navigation completely - fewer pages and more of a single page app style).

Happy to talk this one over in person to see if it's something we should land or not.

@devoncarew
Copy link
Member Author

The page for a class (unchanged):

Screen Shot 2022-04-11 at 10 40 25 AM

The page for a top level library constant (unchanged):

Screen Shot 2022-04-11 at 10 40 39 AM

The page for a class constructor (changed to no longer have sibling class members in the left nav):

Screen Shot 2022-04-11 at 10 41 20 AM

The page for a class property (changed to no longer have sibling class members in the left nav):

Screen Shot 2022-04-11 at 10 40 55 AM

@Levi-Lesches
Copy link

For what it's worth, I use the sidebar for classes to compare different methods/properties. But it's not that big a deal for me to just go back to the class page (or have that open in its own tab).

@devoncarew devoncarew marked this pull request as ready for review January 31, 2023 21:59
@Levi-Lesches
Copy link

As of version 6.3.0, this is now happening by default. Was that intentional?

@devoncarew
Copy link
Member Author

Note that this PR did not land.

@devoncarew devoncarew closed this Mar 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants