Hello there,

http://api.silverstripe.org got some direly needed attention recently.
It was last updated March 2009 (!), apologies for leaving such a crucial tool in that state.

Notable changes:
* Version specific documentation: http://api.silverstripe.org/trunk, http://api.silverstripe.org/2.4 etc
* Slightly nicer template with a bit of SilverStripe branding
* Google custom search (should be version specific as well, I'm waiting for the index to update)
* Automatic updates (every night from an updated svn working copy)
* Removed the superfluous default wiki pages for every class on doc.silverstripe.com. This means we need a more obvious way to search the API docs as a doc.ss.org search won't return matches for every class).

Now, thats a good start, but I think we can still make this a lot better. We're a bit limited by what phpDocumentor enables us to do, but I think a lot can be achieved just by using templating, css and a dash of javascript.

WE NEED YOUR HELP TO MAKE THIS HAPPEN! You don't need much SilverStripe knowledge for this, its basically working with Smarty templates and phpDocumentor. Please contact me if you are interested in giving back to the SilverStripe project by improving the API docs, and we'll help you get started on running the (pretty simple) documentation scripts.

Specifically:
* Better styling for method listing (too much random indentation and horizontal spacing)
* Make package navigation more obvious (otherwise users will miss the difference between "cms" and "sapphire" packages)
* Reduce the default phpDocumentor clutter (unnecessary line numbers, "tags", ...)
* Add some jQuery to auto-hide inherited properties (and expand on click)
* Improve landing page for every release (link to doc.ss.org, installation instructions, upgrade notes, changelog)
* Show method/property detail listing directly instead of the massive anchor link index at the top of class documentation
* Remove the file listing in sidebar, and increase visibility of class listing
* Make the sidebar (class listing) scrollable (pseudo frameset)
* Bring the horrible table-based templates into 21st century

Good examples we can learn from:
* http://api13.cakephp.org (very clean and useable)
* http://www.symfony-project.org/api/1_4/ (good overview with short class descriptions)
* http://api.rubyonrails.org/ (very detailed documentation, although presentation is not that great)

In general, I'd be interested to find out how many of you plan to use the (improved) API, and in which context (looking up a single method signature, learning about a new feature, etc.).

Feedback welcome!
Ingo

Is it possible to have the old urls redirect to the new ones, rather than just 404'ing?

Most of the links from google searches and also docs.silverstripe.org are no longer working..

Good point, done. Its not 100% as lots of classes have been put into a "@subpackage" since the last api.ss.org publication of March 09, have moved to a different folder, or ceased existing in the current form (e.g. ecommerce module classes). I've checked some Google results, fundamental stuff like DataObjectDecorator redirects, but others like MemberTableField doesn't, as it switched packages from "sapphire" to "cms". Feel free to compile a list of redirects in .htaccess mod_rewrite format, and I'll put the rest in ;)

As for docs.silverstripe.org 404 links, I think these are a bit more crucial. I've run a regex over the content to point all api.ss.org links to the trunk/ subfolder, but that will not have worked in all cases for the same reasons stated above - perhaps somebody wants to run docs.ss.org through a linkchecker?

gotapi.com sounds like a good alternative to the (pretty generic) Google Custom Search we have at the moment. I've removed this search in preparation for inserting a gotapi.com widget in its place.

Alright, I've restructured and restyled the phpDocumentor templates heavily, should be a lot nicer now: http://api.silverstripe.org/

The start page also has listings for all of the "SilverStripe" supported modules as well, e.g. blog at http://api.silverstripe.org/modules/blog/trunk. At the moment they're only in trunk, both nothing really prevents us from publishing other versions.

Outstanding work:

* Make package navigation more obvious (otherwise users will miss the difference between "cms" and "sapphire" packages)
* Improve landing page for every release (link to doc.ss.org, installation instructions, upgrade notes, changelog)
* Make the sidebar (class listing) scrollable (pseudo frameset)
* gotapi.com integration/search

I'm really keen on your feedback - after all, this shouldn't just be a pretty compilation of code, but the first point of reference for any API related questions. Or to rephrase: Unless developers have a way to quickly search, access and understand the information presented on api.ss.org, they'll resort to reading the PHPDoc comments in sourcecode. So... as a developer, do you think you can use the API docs in their current form for your day-to-day programming?

Looks nice Ingo. Couple of things I might suggest, or at least trigger a discussion on:

* search
* classname/filename - why do we have them both listed separately? If we took out the filename-based items, the left hand list would be much shorter. I don't really think we need them, as all the info should be in the class with the same name anyway, but if there was a reason to keep them, how about popping files/classes in tabs?
* as well as the landing pages for the releases, something for the package landing pages as well
* possibly links to previous/future versions of each class (ie if I google search and come across DataObjectSet for v2.3 there should be a link to DataObjectSet in 2.4 somewhere useful
* links to the source code in trac

> classname/filename - why do we have them both listed separately? If we took out the filename-based items, the left hand list would be much shorter. I don't really think we need them, as all the info should be in the class with the same name anyway, but if there was a reason to keep them, how about popping files/classes in tabs?

Yeah I was thinking about that - thought somebody might want to find out what _config.php files are for (which wouldn't show in any class listings). At the moment most "non-classy" PHP files are filtered out anyway, so yeah the file listing is pretty nonsensical. Does anybody else have a use case for it?

> * possibly links to previous/future versions of each class (ie if I google search and come across DataObjectSet for v2.3 there should be a link to DataObjectSet in 2.4 somewhere useful

Good point, its already in the top navigation, but the URLs are pretty "guessable", should be able to link directly to them in other version. This will generate some broken links though (renamed classes like HTTPResponse->SS_HTTPResponse, as well as non-existing ones, e.g. Aggregate didnt exist in 2.3). Do you think thats acceptable?

> * links to the source code in trac

phpDocumentor has a --sourcecode option, I might give that a go. Trac links will be harder to generalize from a Smarty templating view (I'm not customizing the phpdocumentoar PHP classes at the moment).