API docs: How to help us generate docs

We're in the process of adding more traditional API-style docs to enhance our existing docs. We're adding a small tab bar to a widget page to add navigation to the basics (current markup-driven approach), options, methods and events.

The select menu is the first plugin to be documented this way and we're hoping it serves as a solid template for others to help contribute docs for the other plugins. Please provide feedback or edits to this template via pull requests to make this as clean and useful as possible before we go too far.

http://jquerymobile.com/test/docs/forms/selects/index.html

Each plugin docs page will be moved into a folder named after it for better organization. Here is a quick checklist of all the things you need to do to port an existing plugin page to the new format:

1. Create a folder for the new plugin, name it logically but it doesn't need to exactly match the plugin JS name. For example, the plugin script is called jquery.mobile.select.js, but the new folder is called "selects". Use lowercase names and, only if critical, use a dash (-) delimiter

2. Move the current plugin docs page into this folder and re-name it "index.html"

3. Update all the JS and script references in the head to hop up another level (../). Same goes for the home link in the header. Copy the tab strip markup from the select index page to link to the new API pages. Add in a new section explaining how to call the plugin directly on this basics page.

4. Copy the options.html, methods.html and events.html pages from the selects folder into your plugin page, update the page title and all content to match the plugin you're working on

5. Lastly, you need to open all the other pages it the /forms/ folder and edit the link list at the bottom of each to point to the new path for the plugin docs folder.

Double check all links work to and from this new folder, run a global search for links elsewhere that may point to the docs page you moved. We're going to add in re-directs to point to the new path but this is just a precaution.

Recent development

The UI project is working on an XML-based docs format that can then be pulled into the site docs. Ideally, we'd use that format too, but the timing of when this will be solified is a bit unclear right now so we might need to push forward with HTML and flip this back into XML later.

Planning info here: http://wiki.jqueryui.com/w/page/40995891/Docs2xml

Sample format here for accordion docs: https://github.com/jquery/jquery-docs/blob/master/jquery-ui/accordion/accordion.xml