Hosting multichip docs

[MabezDev]

We need to find a solution to hosting documentation as part of the unification effort. We've outgrown the capabilities of docs.rs and will need a custom solution.

• Hosting: Github pages? A private server? GH pages should suffice I think, but worth exploring other options.
• Landing page: chip picker - Ideally same theme as docs.rs for a seamless experience
• Separate docs builds per chip
  • Where are the built docs stored?
  • Should the documentation building be handled here in esp-hal, or externally in another repo.
• Update the documentation link in Cargo.toml
• Do we want to handle version selection?
  • latest main + last release?

[jamesmunns]

FWIW, embassy's API docs allow for pretty extensive selections of the stm32 families: https://docs.embassy.dev/embassy-stm32/git

Might be worth checking what dirbaio does and if you can take that.

[jessebraham]

* [ ]  Hosting: Github pages? A private server? GH pages should suffice I think, but worth exploring other options.

Github Pages is the easiest and most reliable solution for the time being. We can revisit this in the future if the need arises.

* [ ]  Landing page:  chip picker - Ideally same theme as docs.rs for a seamless experience

We were able to clone the docs.rs landing page and update it to our liking.

* [ ]  Separate docs builds per chip
  
  * Where are the built docs stored?
  * Should the documentation building be handled here in esp-hal, or externally in another repo.

I'm not sure what you mean with regards to storage, the static assets are uploaded to the Github Pages environment (or, if using a traditional web server, the server). Docs should be built in esp-hal where the source lives.

* [ ]  Do we want to handle version selection?
  
  * [ ]  latest `main` + last release?

I think it's best we leave this for a future release.

[jessebraham]

@playfulFence could you give us some updates here please?

[playfulFence]

We decided to host our documentation on GitHub Pages because it's the most suitable for our purposes (the site will be static for the most part, and what-if dynamic moments plain JavaScript would have been completely sufficient for)

I also added a CI job to build the documentation and copy it down to some more or less usable structure.

You can see some inter-result here: https://playfulfence.github.io/esp-hal/

[playfulFence]

In the nearest future it would be nice to add some QoL improvements for generated docs, like returning to landing page and so on...

[jessebraham]

With #1248 this issue has largely been completed, just a few small details left.

[jessebraham]

The final pieces are completed in #1249, so closing this.