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

[japaric]

@nastevens @ryankurte you can go ahead and do the DNS changes to have the books under docs.rust-embedded.org. The required changes are:

• Rename the rust-embedded/bookshelf repo to rust-embedded/docs
• Have docs.rust-embedded.org point to rust-embedded.github.io/docs
• Take down {book,discovery,embedonomicon}.rust-embedded.org

All these should be done at about the same time.

[nastevens]

rust-embedded/bookshelf has been renamed to rust-embedded/docs. DNS changes will be up for PR here shortly.

[nastevens]

Note that until the DNS records are updated the docs are at https://rust-embedded.github.io/docs/

[nastevens]

DNS changes are merged and applied. HTTPS errors are also fixed for the main rust-embedded.org domain, and are provided for docs.rust-embedded.org. Here's the list of URLs for testing:

• http://rust-embedded.org
• https://rust-embedded.org
• http://www.rust-embedded.org
• https://www.rust-embedded.org
• http://rust-embedded.com
• http://www.rust-embedded.com
• http://areweembeddedyet.com
• http://www.areweembeddedyet.com
• http://docs.rust-embedded.org
• https://docs.rust-embedded.org

There are four URLs that aren't working. I think there are issues with the HTTP 301 redirect from AWS to Github over HTTPS, and don't have a clear solution right now. Thankfully these are only redirects, so long as we focus on the main rust-embedded.org domain we're golden.

• https://rust-embedded.com
• https://www.rust-embedded.com
• https://areweembeddedyet.com
• https://www.areweembeddedyet.com

[adamgreen]

http://docs.rust-embedded.org doesn't seem to be working now. It was working yesterday and earlier this morning.

[nastevens]

Thanks @adamgreen. I have no idea why, but the custom domain setting in Github cleared itself. Should be working again.

[adamgreen]

@nastevens Thanks! That fixed it!

[japaric]

@nastevens @ryankurte docs.rust-embedded.org seems to be down again ("There isn't a GitHub Pages site here.").

[nastevens]

Same as last time the custom domain value was cleared from settings. The only thing I could find is related to not having a CNAME file in the repo: tschaub/gh-pages#213. I've put up a PR adding a CNAME file: rust-embedded/rust-embedded.github.io#13

[adamgreen]

Seems to be down again.

I wonder if the CNAME file should be copied into the doc folder as part of the https://github.com/rust-embedded/docs/blob/master/ci/script.sh script since it looks like these CI scripts will do a forced git push and overwrite anything that has been previously merged into the gh-pages branch? Maybe the daily Travis CRON job is what causes the break?

[nastevens]

@adamgreen I think that's it exactly - check out the update times of the gh-pages branch right after I fixed the custom domain through the settings panel:

The UI seems to write that file and commit it as me when I change the setting.

There's even a CNAME option to ghp-import: https://github.com/davisp/ghp-import#usage

[adamgreen]

@nastevens - I like that ghp-import CNAME option solution. Very cool!

[japaric]

This has been done.