switch API from ApiGen to Sami?

Permalink 1 user found helpful
The current API onhttp://documentation.concrete5.org/api/... is created using ApiGen. After using API created using Sami, I think switching to it would save time and add a lot of useful features.

The features that immediately stand out:
- methods are part of search results (including auto-complete)
- you can jump from Classes, Namespaces, Interfaces, and Traits
- there is an index

The Symfony API search auto-completes in a resizable iframe which makes searching faster and easier to see longer namespaces. Please see attached screenshot.

It looks like you can configure whether you want to jump to code or not. Symfony just lists lines and Laravel jumps to code on GitHub. I imagine we would want to jump to code hostedhttp://documentation.concrete5.org/api....

If the core team doesn't have the time to implement this. Is anyone else interested in hosting this?

Sami is open-source Sensio code.
http://fabien.potencier.org/sami-yet-another-php-api-documentation-...

Sami
https://github.com/FriendsOfPHP/Sami...

Laravel API
https://laravel.com/api/master/doc-index.html...

Symfony API
http://api.symfony.com/3.0/index.html...

1 Attachment

MrKDilkington
View Replies:
Mainio replied on at Permalink Reply
Mainio
I see the usability advantages in the tool switching, especially the direct linking to GitHub code and quick switching between versions. But, it does not make the actual API docs much more appealing to me. For me at least, these usability improvements would not make me use these docs much more. I almost never use these docs when working with concrete5.

The biggest thing missing from the API docs currently for c5 are code comments (for the most parts) and the amount of available examples within these comments. This has always been the pain part with c5 and still seems to be. But there has been some good progress going on regarding this after the 5.7 development branch was opened for external users, so I haven't lost hope on this (+ the latest improvements on the docs site are very good progress as well).

The best API docs that I personally really enjoy reading are with Rails. Take a look at their approach on giving the examples (+ you can either directly take a look at the source on the page or click the GitHub link if you want to dig deeper, makes it much quicker to use):
http://api.rubyonrails.org/classes/ActionView/Helpers/UrlHelper.htm...

Of course, they have "a couple" more developers who spend time commenting the code base but just saying, this is what it **should** be in the perfect world.

I also prefer their structure of the page compared to most of the PHP apidoc creators because usually when you're reading these, you're only interested in the one class or the one method you're looking for. No need to show the whole class tree or anything like that in my opinion.

I almost always use these docs when I'm working with Rails.