Host all books under docs.rust-embedded.org

[japaric]

Right we have each book under its own (sub)domain: {book,embedonomicon,discovery}.rust-embedded.org. I was thinking if it would be both less work for the ops team and better for discoverability to have them all under doc.rust-embedded.org/{book,embedonomicon,discovery} (*) and have doc.rust-embedded.org be a landing page that describes the target audience of each book -- in a similar vein to https://doc.rust-lang.org/

Thoughts?

cc @rust-embedded/resources @nastevens @ryankurte

[jamesmunns]

👍 for a landing page.

Additionally, this might be a good place to at least add the embedded-hal docs, and perhaps links to docs for various chip/board support crates that are well reviewed.

[therealprof]

I like it.

[ryankurte]

I like the outcome, (aside from combining the docs repo's into one repo, which is an option) it's gonna take some github tomfoolery to make it work though.

afaik the easiest way to make this work is to create a rust-embedded.github.io site with the CNAME docs.rust-embedded.com and an A record for docs.rust-embedded.com to the GH pages addresses.

This repo will contain the landing page and set the default organisational prefix to docs.rust-embedded.com, then github will match the path against the name of repositories with web hosting turned on under the org. For example https://github.com/rust-embedded/book will automagically be served at https://docs.rust-embedded.com/book.

The implications of this are that we could remove any document-specific configuration from the DNS records, and that rust-embedded.github.io would be redirected by github to docs.rust-embedded.com. We don't currently have a site there, so I wouldn't see that as a problem.

This doesn't change the hosting arrangement for the current https://rust-embedded.com site.

(For reference, this is the setup I use for https://ryan.kurte.nz and subpaths like https://ryan.kurte.nz/doesmybank/)

[japaric]

@ryankurte I forgot to mention but I was envisioning implementing this in a similar way to how (I think) rust-lang/rust does it. Basically, we'd create a docs repo that contains all the books as submodules; we'd set up CI to build and publish the docs to r-e.github.io/docs and we'd have the DNS record link docs.r-e.org to r-e.github.io/docs.

This means that landing a change in e.g. the book repo will not, by itself, update docs.r-e.org/book. To update the hosted docs it would be necessary to update the book submodule in the docs repo. Though, it might be possible to set up some sort of CI script that runs on successful merges to e.g. book's master and updates the book submodule of the docs repo.

Would that be simpler from the point of view of managing the DNS records?

[ryankurte]

Ooh, so the submodule approach the docs repo would call into each module to build then assemble the outputs somehow?
I think the exploiting github approach is simpler, but, either sounds fine to me ^_^

[japaric]

@ryankurte yep, the docs repo would generate a /index.html file similar to the one in docs.rust-lang.org (I think they use rustdoc for that one?) and then build each mdbook and put them in /book, /embedonomicon, etc.

[japaric]

The bookshelf is live at https://rust-embedded.github.io/bookshelf/

Repo: https://github.com/rust-embedded/bookshelf

[japaric]

I think it's time to put the bookshelf on rust-embedded.org. We need to decide on a place so let's do a poll using emoji / GH reactions. Options:

• 👍 doc.rust-embedded.org
• 🎉 docs.rust-embedded.org
• ❤️ bookshelf.rust-embedded.org

How to vote: review the contents of https://rust-embedded.github.io/bookshelf/. If you are happy with it cast your vote by adding a reaction to this comment. If you'd like to change something open an issue / PR in the bookshelf PR.

r? @rust-embedded/resources cc @rust-embedded/all

[japaric]

docs.rust-embedded.org seems to have the majority of votes. Follow up question: should we rename the bookshelf repo to "docs"? Please vote:

• 👍 yes
• 👎 no