[Documentation] Overall as well as indirect - Rack::Handler:: specifically

Hey there folks,

After a hiatus, I am back using sinatra. A lot of my old code currently does not work, for many reasons (my own fault too, but in a bit external too).

For instance I was using this in the past:

Rack::Handler::Puma

Or:

Rack::Handler::Thin

It seems Rack::Handler is no longer available though. I am using the latest rack + sinatra right now.

Now, Rack is not the concern of Sinatra, I get it. But here I am now faced "what to do?"

I'd perhaps like to have something like that via Sinatra, like:

Sinatra::Handler::Puma

Does not have to be the same API. Perhaps it could be:

Sinatra.webserver = :Puma

Or some API like this. That way I could port things more easily. This issue, though, is not primarily about that.

Sinatra does actually have pretty solid documentation - not perfect but quite useful. Just compare that to ruby WASM or ruby opal - their documentation is so much worse.

The primary entry point I use is this here:

https://sinatrarb.com/intro.html

It's a long page, but this is still good because it contains a LOT of useful information. I also keep information locally, but sometimes I have to update this information.

Yesterday I looked at https://sinatrarb.com/intro.html and I actually learned a few new things.

For instance, subclassing from Sinatra. It was recommended to use:

require 'sinatra/base'

but also:

class Foobar < Sinatra::Application

I was unaware of the latter, so it is REALLY nice to have information available online.

I would still like to recommend to improve that webpage, and ideally add more useful documentation too. It does not necessarily have to be on that page, but could be linked in to other pages, perhaps a bit of a wiki style.

I don't know the internals well, but if anyone understands the internals, it would be nice if a paragraph could be added as explanation about the Rack::Handler::Foobar part, and how it relates to sinatra. And whether we could have an API such as Sinatra.webserver = :Puma or something like that, that could also be mentioned either on that page, or in a separate "advanced knowledge" document or so.

Right now I am slowly going through that page and try to collect useful information into my own local knowledge base (I use my own local knowledge base primarily because I can modify it, style it differently, add more information to it etc... so this has advantages for me, but for new knowledge I kind of prefer such a single website with a lot of information).

One thing that I would recommend is to show when the page was last updated, somewhere on the bottom. Right now I don't know when the page was last changed, could be years ago, could be more recently. (And perhaps also link in to github changelog for that page if possible).

Anyway, this issue can be closed - hopefully someone can read through it and then consider it a bit before closing. Thanks for reading! Sinatra is at its core really simple.