Simplify and improve documentation by moving to docs.rs

[acud]

Greetings.
I've spent the last few days onboarding to sqlx and I'd like to share my impressions so far from the documentation experience. Some things can be improved such that onboarding is made easier.

• Stands out as a starting point the fact that the docs.rs entry reflects the fact that there's no base crate documentation. Taking packages like axum (which IMO have a very approachable documentation), the crate has extensive documentation at the base which highly contributes to its approachability - have a look at the TOC, with clear examples on how to use every component, even if on a very basic level. This helps keep a high-level reference on syntax and crate idiosyncrasies on the onboarding phase
• Most of this high level documentation is kept on on the GitHub readme. This is problematic because:
  • The code may change and since the readme isn't build from the source code comments it means that even if someone changes the rust doc comment, another manual change must come to the readme file.
  • One must constantly juggle between Github (to have the overview), examples (because even the code examples in the readme are limited) and the docs.rs page (for extensive package documentation) which is clunky and confusing
• Another issue which is caused by this is that drill-down from the github docs into the docs.rs docs is not possible due to the way that syntax highlighting differs between github and docs.rs - while docs.rs has syntax highlighting that supports having embedded hyperlinks, github does not (example for axum here)
• usage of local package documentation using cargo does not live up to the potential (cargo doc)

As of such I propose the following actionable items in order to improve the package documentation:

• cut the readme to the bare minimum and avoid code examples. Maintain only build related instructions and code license & contributing guidelines.
• move the main mass of information from the readme to the crate-level documentation

later on, the docs could be further worked on through the builtin rust doc, rather than on the readme and examples.

The benefits of doing it this way over the existing doc setup:

• single entry point for the documentation. one can keep an overview both about package general ideas and concepts, and can also drill down into the details (which is direly missing at this point)
• easier for maintainers - less things to keep a mental model of; one single source-of-truth for docs
• local documentation can be used (using cargo doc)