`docs_main.cr` is a mess

[straight-shoota]

docs_main.cr serves as entry point to generate the API docs for the standard library. It requires all files that contain documented features.

It's quite a chaotic mess.

Entries are unordered. That's probably due to some forced order dependencies, not sure about the details.

Many entries are omitted because they're already required as part of the prelude or are transitive dependencies of others. This makes it hard to follow which files actually end up being included in the docs.

There's generally quite a bit of overlap with prelude.cr. But it's inconsistent because some parts of the prelude are also in docs_main.cr (require "array") while others aren't (require "base64"). It would be cleaner to either embrace the prelude and remove duplicates, or spell out all requires in docs_main.cr explicitly and even remove the prelude from the docs build (crystal docs src/docs_main.cr --prelude=empty). I don't think removing the prelude makes much sense. It would allow us to exclude files that don't contain any documented features, but they might be implicit requirements of other code that's relevant for documentation.

It would also be helpful to have a reminder to ensure newly added files are present in docs_main.cr. That's a relatively rare event, so we don't always remember it (see #14624). Most new files are added to paths like src/compiler, src/crystal or src/lib_c anyway, which can be ignored for docs. Not sure if there's an easy way to do this, though. It might not be terribly relevant because we should usually notice if API docs are missing when preparing the release notes, so we should be able to fix it in time before a release.

So I'd suggest to do the following:

• Remove all entries in docs_main.cr which are already in prelude.cr.
• Order all entries in docs_main.cr by path. If there are any forced order exceptions, document them (like in prelude.cr).
• Consider if we can add some kind of automation to alert us of adding new files to docs_main.cr.

[ysbaddaden]

I wish we had a folder for std (e.g. src/std), then docs_main.cr could be (almost) reduced to:

require "./annotations"
require "./compiler/crystal/macros"
require "./std/*"
require "./docs_pseudo_methods"