Improve UX for Material API documentation

[ThomasBurleson]

The current API section of the Angular Material documentation needs improvements. We should consider:

• the API presentation in UI Router

• the API documentation for AngularJS 1.x

• the planned API docs for Angular 2.x. (talk with @petebacondarwin )

  We may need to enhance our jsDocs, update the gulp and CSS, etc.

Checklist:

• Docs menu items in more common Guides/Tutorials/Resource structure (IA), restyled to use expand/collapse list controls Updated Docs Sidenav, new Getting Started page #1116
• Add real-world examples Change plunker codepen and jsfiddle links to "hello worlds" #1102
• Restyle API services & directives into more readable format Docs: Restyle API methods, attributes and parameters into more readable format #984
• Simplify API toolbar buttons, add Search Implement Search feature in the Material online docs #917
• Add version picker Provide versioning of Online Docs #918

[ThomasBurleson]

API Sample:

API Sample:

[petebacondarwin]

@ThomasBurleson - I would really like it if you could combine efforts, or share ideas, with our "Materialize the Docs" team. We have a doc and a branch.

[ThomasBurleson]

@petebacondarwin - Can you include @marcysutton as a contributor on your efforts. She will be the liaison for Docs between Angular and Material. And we would love to help materialize your already amazing docs.

[ThomasBurleson]

Other considerations for Angular Material Docs include:

• Search results
• Version switcher
• Breadcrumbs
• Submenus
• Keyboard navigation / accessibility
• Navigable for visually impaired persons / accessibility

base on the Angular 1.x Doc Improvments notes

[marcysutton]

@petebacondarwin has there been any planning with regard to the UI design for the new Angular.js docs or is this being iterated upon in development by each contributor? The visual state of the Materialize the Docs branch looks pretty raw (color contrast issues, typography not following spec, etc.). Accessibility features obviously can be worked into the codebase via PR's, including skip links, focus management and correct ARIA usage. I just want to get a handle on how the design is being handled.

I also noticed PRs merged directly in that branch instead of patching commits to master. Are there any concerns about polluting the changelog (feel free to tell me to move this conversation to another place)?

[petebacondarwin]

@caitp is looking after that project. None of the people working on it have strong desigo skills.

[marcysutton]

@petebacondarwin @caitp one more question: @ThomasBurleson outlined "API documentation for AngularJS 1.x" and "the planned API docs for Angular 2.x" at the beginning of this issue as things to consider with the Angular Material docs. Are those actually separate efforts, or does "Materialize the Docs" fit into one or the other?

[petebacondarwin]

They are separate efforts right now. Well really the 2.0 doc gen is just me so they are closely related.

[epelc]

Please do not base it too heavily on ui-router's docs. I find them extremely lacking and I always have to jump between them and their wiki pages.

[marcysutton]

@epelc the only part of UI-Router's docs that was considered was how methods are displayed. But I will keep that in mind.