api.silverstripe.org needs some love - can you help?

[Ingo Schommer]

Hello everybody!

Our API docs at http://api.silverstripe.org have been based on heavily customized phpdocumentor setup for a while.

We've changed the templates to be more easily scannable, and added an XML export which

is imported into a custom SilverStripe search engine. 

All of this is clumsy to maintain, and slow to use. Parsing takes ages, and frequently breaks execution on benign PHPDoc syntax errors.

Which is part of the reason we still don't have a 3.1 version on there. I think we can do better.

Is anybody willing to evaluate and implement an alternative? 

I think the choice is between PHPDoc2 (http://phpdoc.org/) and SAMI (https://github.com/fabpot/sami), but happy to hear about alternatives.

Here's some decision criteria:

- Supports PHPDoc

- Solid generator

- Built-in search for class and method names

- Readable and "scannable" presentation

- Hackable URLs (which we'll need to plug into the doc.ss.org "shortcuts" to the API docs)

- Deep links via URL to properties etc.

- Git branch/tag support (or minimal scripting work required)

- Support for namespaces, but also provides meaningful interface without them

- Nice to have: Supports markdown (or some non-HTML way to define basic structures like lists and headlines)

- Nice to have: Opensearch support

Some observations about the two solutions above:

- PHPDoc2 is in alpha, has 120+ bugs in github

- SAMI doesn't seem to be very active, but generally anything from @fabpot is solid work

- SAMI default template looks prettier than PHPDoc2 ;)

So, ideally you can set up an instance somewhere and we can check it out.

The idea is still to run it on api.silverstripe.org eventually, of course.

Even if you don't have time to take this on,

I'd love your feedback on if/how you use the existing API docs,

and what would make the system more useful to you.

Thanks

Ingo

[Ingo Schommer]

OK, not exactly an overwhelming response...

I've chosen on a third alternative, http://apigen.org. Turns out to be easier than battling PHPDocumentor on 3.1, and fixing its random fits.

Will also help with the transition to namespaces (PHPDocumentor 1.x doesn't support them).

Apigen satisfies all of the criteria I've outlined, apart from Markdown (supports Texy, which is similar).

And it uses a pretty bootstrap template, and has built-in search. 

Check out the SilverStripe docs (master branch) on http://test.silverstripe.com/apigen/htdocs/trunk/.

The code is also on Github now (both old and new): https://github.com/silverstripe/api.silverstripe.org/tree/apigen

I'm going to switch api.silverstripe.org to this new generator next week unless I hear any significant concerns.

Todo:

1. Creating mod_rewrite rules from old to new link styles

2. Replace API lookup links from doc.ss.org with a simple PHP rewriter (Example: http://api.silverstripe.org/search/lookup/?q=Controller&version=3.0&module=framework)

3. Add github contribution link to bottom of template

4. Fine tune design: Links in SilverStripe blue, lighter header

5. Add version selector dropdown to template (preselected to currently shown version)

6. Enable Google CustomSearch and Google Analytics (once live)

 

I could use help on any of the above - they don't require much PHP or Apigen knowledge,

so if you have a spare hour somewhere, I'd really appreciate a helping hand :)

Thanks

Ingo

[Fred Condo]

On Feb 15, 2013, at 9:05 AM, Ingo Schommer <ingo.s...@gmail.com> wrote:

> 1. Creating mod_rewrite rules from old to new link styles

I can help with this bit.

[Ingo Schommer]

Thanks Fred - so you need any more help to get started?

In the end, the rewrite is roughly: /\/(.*)\.html/ => class-$1.html (pseudo-regex).

Plus the version prefix of course. I think we can ignore anchors and secondary views like "by package" or "all classes" for now.

[Ingo Schommer]

Hey Fred, did you make any progress on the rewriting rules? :)

[Fred Condo]

On Feb 19, 2013, at 2:44 , Ingo Schommer <in...@silverstripe.com> wrote:

> Hey Fred, did you make any progress on the rewriting rules? :)

Hi Ingo,

My Mac is building the docs now so I can test the rewrite rules!

[Fred Condo]

On Feb 15, 2013, at 9:47 , Ingo Schommer <ingo.s...@gmail.com> wrote:

> Thanks Fred - so you need any more help to get started?

Pull request submitted: https://github.com/silverstripe/api.silverstripe.org/pull/1

[Sam Minnée]

OK everyone,

At Ingo's request I've updated the api.silverstripe.org domain to point to the new version of these docs; the new API docs should be appearing to you soon.

If anyone has any issue, please let us know.

Thanks

Sam

[Daniel Hensby]

Using a nexus 7 running chrome, you can't scroll either pane. :-(

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to silverstripe-d...@googlegroups.com.
To post to this group, send email to silverst...@googlegroups.com.
Visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Ingo Schommer]

Yep, it would be good to have api.ss.org have a more responsive layout.

and bootstrap seems to provide some starting points for this. Any takers? :)

Also, please file issues on https://github.com/silverstripe/api.silverstripe.org.