#155 enhancement
Nick Stakenburg

Change Pdoc navigation and sections

Reported by Nick Stakenburg | March 8th, 2010 @ 05:56 PM

I think some changes to the Pdoc navigation could do the documentation justice. I made a mockup that takes the navigation closer to that of the old Prototype API:

http://nickstakenburg.com/images/temp/pdoc_prototype_navigation_2.jpg.

The idea is to have it work like the old API but have things expand like the new API where it makes sense.

The first documentation page is the readme with the global object menu on the left, this menu doesn't expand and can have some optional sections. With one click you can get to the documentation pages of the global objects and sections. On those pages there's an extra menu above the global object menu showing the current object. Everything in the current object menu is collapsed and can expand on click, besides the expanding you'll always get to see a documentation page after a click. Search can save a few clicks when you are looking for a deeply nested method.

To make this possible most sections would have to be taken out of the documentation and sections would have to work differently in the navigation. I'm not sure if Pdoc can handle all of it though.

Right now everything is tagged to be in a section:

/**
 *  == Ajax ==
 *
 *  Prototype's APIs around the `XmlHttpRequest` object...
 *
**/

/** section: Ajax
 * Ajax
**/

/** section: Ajax
 *  class Ajax.Request
 *
 *  Initiates and processes an Ajax request.
**/

What I'm suggesting is to have everything you create be in a global scope instead of a section. In the example below the documentation of the Ajax section was moved to the global Ajax namespace.

/** 
 * Ajax
 *
 * Prototype's APIs around the `XmlHttpRequest` object...
 *
**/

/**
 *  class Ajax.Request
 *
 *  Initiates and processes an Ajax request.
**/

That could make the nicely sorted global object menu possible.

Then there's the Utility Methods folder in the mockup, the only one Prototype really needs. Maybe sections as they are now can be used to create these folders.

/**
 *  == Utility Methods ==
 *
 *  Prototype provides a number of “convenience” methods...
 *
**/

/** section: Utility Methods, related to: Element
 *  $(id) -> Element
 *  $(id...) -> [Element...]
**/

In the mockup these sections act like folders so that they appear above everything else. I was thinking about nested sections but that probably adds another layer of complexity, maybe there's no need for it?

Hope that makes sense.

Comments and changes to this ticket

  • Samuel Lebeau

    Samuel Lebeau March 10th, 2010 @ 11:44 PM

    • State changed from “new” to “enhancement”
  • Tobie Langel

    Tobie Langel March 10th, 2010 @ 11:58 PM

    Thanks for your suggestions Nick.

    As I mentioned over Twitter, sections are here to stay (notably for the modularity we'll be introducing with Prototype 2.0).

    That said I'm opened to change / improvements on the menu (and elsewhere).

    I suggest you implement your changes in a branch so we can have a look (and more importantly a feel) of your proposal.

    You might want to wait until I push a bunch of commits I've been working on as there's a lot of changes in the API.

Please Sign in or create a free account to add a new ticket.

With your very own profile, you can contribute to projects, track your activity, watch tickets, receive and update tickets through your email and much more.

New-ticket Create new ticket

Create your profile

Help contribute to this project by taking a few moments to create your personal profile. Create your profile ยป

Shared Ticket Bins

Pages