Silverstripe-framework: RFC: Upgrade API docs generator

[unclecheese]

The docs generator we use on api.silverstripe.org is Sami which is currently deprecated and points to an archived repository. It has not been upgraded for compatibility with PHP 7 type hints, and this is a growing problem.

We've done a couple of major overhauls to our docs sites, particularly docs.silverstripe.org and userhelp.silverstripe.org recently. Also, I recently migrated api.silverstripe.org to Netlify/Lambda as an experiment and it seems to be working well.

It feels like apt timing to discuss upgrading the docs generator tool. A quick search around didn't turn up too many promising options, but the two main candidates I found that have seen activity within the last year are:

• phpDocumentor -- Ugly templates. Navigation experience doesn't hold state in the demo, which is annoying, but hopefully not an insurmountable problem.
• phpDox -- Also quite an ugly demo that is not responsive, but boasts fasts build times, which is supported by their own data for major libraries.

Seems like the table stakes are:

• Cannot require any major inputs of design time (unless a community member wants to contribute it)
• PHP 7 compatibiltiy
• Adaptable to work with search (I think we should migrate to Algolia, which has been a positive outcome for docs)
• Will likely require an update to the lookup script
• Similar enough URL pattern for easy 301s
• Can be deployed to a static hosting provider

Does anyone have any experience with the above tools, or others that might satisfy these criteria?

[robbieaverill]

I have a feeling that Symfony were using sami (may be wrong), but might be worth some recon to see what other frameworks use?

[unclecheese]

Yes. One of these two does the docs for symfony and phpunit. I believe it’s phpDox.

[stevie-mayhew]

I've been working on a Sami PHP7.4 upgrade for my org as unfortunately phpDox and phpDocumentor just don't generate nice documentation (IMHO)

Unsure if it would be suitable, but I imagine that actually maintaining a fork might be a good option. I'd probably be happy to do that under my organisations umbrella.

Laravel is still using Sami (https://laravel.com/api/5.8/) so I imagine there is appetite for it outside of our own repositories.

[chillu]

OK, let's see what Laravel and Symfony work out. It's a bit unfortunate that there's no rationale for archiving the repo, and I can't find any next steps for symfony (after searching). I suggest that we stay on Sami as long as we can, even if that means not being able to expose PHP 7.4 stuff. On the assumption that Sami continues to generate meaningful API docs for us. There's a bunch of existing issues on the api repo, some of which were simply due to switching to the Sami generator and it's default templates.

We have ~2k users per month on the API site, so enough usage to keep it going. But my appetite for spending SS Ltd time on rebuilding it just for the sake of being on a supported library is close to zero. This could become a community maintained resource?

@unclecheese What's left to do in order to get this on netlify?

[unclecheese]

Open todos are tracked here https://github.com/silverstripe/api.silverstripe.org/pull/89

FWIW, I got a bit ambitious and wrote a renderer for Sami that just outputs the docs as JSON structures, so if we ever wanted to, we could do the whole thing in an SPA. 🤗

[chillu]

so if we ever wanted to, we could do the whole thing in an SPA

Yeah, if we wanted to write views for the hundreds of permutations of displaying API docs, then we could do that. Which we don't. :D

[unclecheese]

Hundreds? There's like four templates! https://github.com/silverstripe/api.silverstripe.org/tree/master/conf/themes/silverstripe

[williamdes]

Hi,
Sami can be replaced by Doctum it's fork.

Laravel is still using Sami (https://laravel.com/api/5.8/) so I imagine there is appetite for it outside of our own repositories.

Now it is using Doctum

Let me know if a pull-request is needed to make the replacement

[Cheddam]

@williamdes We'd welcome one 😄

[williamdes]

@williamdes We'd welcome one

Here it is ;)
https://github.com/silverstripe/api.silverstripe.org/pull/90