Docs2xml

Page history last edited by Richard D. Worth 7 months ago

Goal

Convert jQuery UI API docs from MediaWiki templates to new (in development) XML templates to support new (in planning) api.jqueryui.com site. Share XSL and CSS stylessheets with other API docs (Core, QUnit).

Current State (MediaWiki templates)

The jQuery UI API docs are currently (as of 1.8 releases) in MediaWiki template format.

The originals are at http://docs.jquery.com/UI/{Pluginname} which redirects to the latest version such as http://docs.jquery.com/UI/API/1.8/{Pluginname} .
An example is http://docs.jquery.com/UI/Dialog which redirects to http://docs.jquery.com/UI/API/1.8/Dialog .
You can get the raw MediaWiki template content by http://docs.jquery.com/action/raw/UI/API/1.8/Dialog (note: due to content type, browser will download as file)
You can view the rendered html content by http://docs.jquery.com/action/render/UI/API/1.8/Dialog

As part of the build process, this rendered html file for each plugin is stored in the docs folder of the development bundle as well as used for the documentation shown on jqueryui.com/demos and jqueryui.com/docs.

New XML templates

The new XML templates format is being developed in a github repo at https://github.com/jquery/jquery-docs . If you need commit access, contact anyone on the jQuery UI team (Scott, Richard, Dan, Jörn).

It is based on the XML and XSL used on api.jquery.com site. Changes are being made to support different needs jQuery UI plugins have, such as documenting methods and events. Options are used for two or three methods in Core, but are much more important for jQuery UI.

XML Spec(ish)

A pseudo-example of the latest proposed XML format can be found at https://github.com/jquery/jquery-docs/blob/master/spec.xml . Pseudo-example because it is neither a spec nor an example. It contains some element and attribute names and some comments, also some pipe-separated attribute values where in actual use only one of the values would be present at a time.

XML Sample

Some progress has been made on porting the Accordion docs to this new XML format, as a test of the spec as well as a reference for further discussion https://github.com/jquery/jquery-docs/blob/master/jquery-ui/accordion/accordion.xml

XSL

This file should transform the above sample XML file into a semantic HTML file suitable for standalone use as well as display on api.jqueryui.com https://github.com/jquery/jquery-docs/blob/master/entries2html.xsl

GitHub for managing content, WordPress for presentation

We have a script to migrate XML docs content authored and managed in GitHub to be posts in WordPress. This is similar to how current api.jquery.com works in that it uses WordPress to render XML docs as WordPress posts content. It's different in that GitHub is used to edit and version the content, rather than wp-admin's text editor.

Posts are edited in GitHub, only latest version is put into WordPress wp_posts table

The latest version of each docs XML file is used as the only (and published) revision of each post in WordPress. Because GitHub handles versioning, no older revisions are saved in the WordPress mysql database and it's not suitable to modify the content using the WordPress editor as any changes will be overwritten. This is a one-way migration.

Pages are edited in WordPress

For now the GitHub script only imports posts (API Entry XML). Pages should be edited in WordPress. We should consider whether pages should also be managed in GitHub, perhaps using markdown.

The script - git2wordpress.js

The script is at https://github.com/jquery/jquery-docs/tree/master/git2wordpress

How it works

The script depends on a clone of the git repo being checked out on the server that has access to the WordPress mysql database. It first does a git pull to get the latest content. It then walks through the specified directory and processes each .xml file. For each file it computes a slug based on the filename. If a post with that slug exists in the wp_posts mysql table, it updates the content. If a post with that slug doesn't exist, it inserts a new post with the content.

How it runs

For now it runs manually by

node git2wordpress.js

The script could be set to run using cron or from a GitHub commit hook.

Next steps

Figure out if we can have xml files extend other xml files. This way things in the widget factory can be documented in the widget xml https://github.com/jquery/jquery-docs/blob/master/jquery-ui/widget/widget.xml and then not duplicated in each xml file that references the widget xml (entry of type "widget"). This same inheritance/extension mechanism could work for further levels of extension, as it basically parallel the widget inheritance/extension.
Finish the XSLT
Script a conversion of the source (raw MediaWiki or rendered html) to xml of all the existing documentation
Design some decent css for preview/testing (using styles from api.jquery.com right now)
Finish some much better css for displaying docs on api.jqueryui.com