Add a Tasks list to the left column. #357
Conversation
|
Need to update the integration specs repo. |
| if task[:name] | ||
| { name: task[:name], url: "#/"+task[:uid] } | ||
| end | ||
| end |
There was a problem hiding this comment.
Sorry, my ruby-fu is fairly undeveloped - where should I put the .compact? I see in the docs that it "Returns a copy of self with all nil elements removed.", but I'm checking a child element of task (:name), not the task itself.
There was a problem hiding this comment.
Just put it at the end of this line, otherwise the array you're mapping to can contain nil
There was a problem hiding this comment.
Shouldn't you use tasks.flat_map instead of tasks.map?
There was a problem hiding this comment.
Unless I've been ruined by Swift and Ruby's Array::flat_map doesn't reject nil elements?
There was a problem hiding this comment.
$ irb
2.2.0 :001 > [1, 2, 3].flat_map { |x| x * 10 if x > 1 }
=> [nil, 20, 30]
A case Ruby is actually stricter than Swift. Inform the media!
|
I have mixed feelings about this. As you point out, this makes it much harder to navigate between classes. Also, the left sidebar already has serious scrolling issues in general (sometimes I can’t get it to scroll at all, and instead the whole doc scrolls). That will only get more annoying if the content gets taller. I do see the advantage of having the task list at the ready, though. Do you mind posting a screenshot, or a link to docs build with your PR? |
|
Screenshot: |
|
re: content jumping around. Jazzy's side bar is presently a "top-level site nav". Apple's docs, on the other hand, only use the side bar for links either within the page or related to the page. Top-level site nav is available at the framework index page. I'll admit that my pull request is conflating the two. Perhaps a discussion needs to be had around what should go in the side bar? One could argue that placing the site nav in the sidebar is optimizing for quickly jumping between classes, while I'd wager that someone viewing a particular class would prefer quick access to the internals of the doc (via the Task List) or related APIs. The latter is how Apple's docs are structured as far as I can tell. Happy to work with y'all to find a solution here :) Not sure how strongly the opinions are on the content currently in the sidebar. Reference content: |
I think you’ve hit the nail on the head here. I would like to see this worked out, though; it bugs me a little too. Two important differences in the Apple case:
|
|
To summarize the things that are missing that could help jazzy's overall navigation: Per-API
Top-level
|
|
Related documentation is already available via |
|
Ah true :) Though I was referring specifically to including Related Documentation in the side bar. Does jazzy already do that? |
|
Good points. I agree, and we're already tracking all of these:
README, as you mentioned. This is configurable from the command line / YAML file too.
Not quite covered by #8, but could be an expansion thereof.
What do you mean by this? |
That the top level page would consist of a readme, class hierarchy, and then all of the other top-level symbols (enums, c functions, etc...) |
|
I see that as an extension of your other points, and yes it would be good! |
|
It would be nice to see some ideas mocked up with actual libraries. Maybe we could even involve a real live designer. (!) I have a feeling that Apple’s doc design is better suited to their behemoth framework than to our little libs. Even RestKit is but a pebble at the feet of UIKit. |
|
I'm going to close this now that there is support for themes. If themes don't prove to solve some of the issues outlined in this PR we can reopen and revisit the thread :) |
Similar to Apple's docs, this "Tasks" section shows all of the task section on the current page.
I've put the Tasks list above the other links which makes it a little harder to jump between APIs because the Tasks list might grow/shrink/not exist. What are your thoughts here @jpsim?