Decision: Where should the embedded books live?

[jamesmunns]

We had an offer from @steveklabnik to host any of the embedded books we would like on the official doc.rust-lang.org bookshelf.

Pros:

• Greater visibility
• Makes embedded look more official
• Books become available offline, as they are distributed through rustup

Cons:

• Book update process requires a manual PR to update
• If we have duplicate copies between docs.rust-embedded.org and doc.rust-lang.org, thats probably bad for SEO, and might cause confusion.

In IRC, we came up with the following possible solutions:

1. Move all embedded books, even the not-so-polished ones, to doc.rust-lang.org
2. Keep all books only on docs.rust-embedded.org
3. Move only "the book" to doc.rust-lang.org, treat docs.rust-embedded.org as "the embedded docs nursery"
4. Host docs in both places

[adamgreig]

We could also see if we can have a link to the rust-embedded bookshelf from the rust-lang bookshelf? I don't know how that interacts with offline copies via rustup.

[steveklabnik]

Anything not in the main rust repo does not get distributed offline.

[adamgreig]

@steveklabnik but can the docs link to online content which is not distributed offline? Would it be OK to have a link to our online bookshelf inside the offline docs?

[steveklabnik]

We can technically, but it's a frustrating experience for users, so we try not to as much as possible. I would prefer to not except in extremely extenuating circumstances, of which I don't think this is.

[adamgreig]

That's fair and sort of what I expected, thanks for clarifying!

[Ravenslofty]

I think 3) is best; having the book in docs.rust-lang.org gives it an "official" air, so it should be good quality. It also attracts more eyeballs, which is useful for attracting attention.

[jamesmunns]

Yeah @ZirconiumX, I agree. My vote would be 3), with a link to the doc.rust-lang.org copy of the book on our landing page. This way we still have the "landing page" which points to all the books in one place, and by then, the users probably don't care whether the links take them to docs.rust-embedded.org/book or doc.rust-lang.org/embedded-book/

[jamesmunns]

Hey @rust-embedded/all - if no issues are raised, I would like to go with the following plan:

1. Open a PR to the upstream doc repo adding the Embedded Rust Book as a submodule there
2. Change the link on https://docs.rust-embedded.org/ to point to https://doc.rust-lang.org/embedded-book/ (or whatever path @steveklabnik would suggest) for the "Embedded Rust Book"
3. Update the new website (not yet public) to point links to the "centralized" copy of the book
4. Add a robots.txt to our copy of the book (https://docs.rust-embedded.org/book/), preventing it from being crawled.
5. Replace all current pages of https://docs.rust-embedded.org/book/ and children to be 300 redirects to the "centralized copy"
6. Rename our copy to something like https://docs.rust-embedded.org/nightly-book/ - to make it clear what the purpose of this copy is. Still with an aggressive robots.txt to prevent search engines finding it

If there are no objections, I'd like to start this process by the end of this week, so if you have concerns, please raise them early so we can address them quickly (or come up with another plan).

Edit: I believe this meets our goal of the following:

• Centralized place for finding embedded docs - https://docs.rust-embedded.org/ - this page will still link to all books, whether they are hosted "here" or "there"
• We get the "official" looking presentation of our book being with the rest of the books
• Our book gets distributed for offline consumption
• We have a path for migrating other books in the future
• We still have a nightly build of our book for review, and can use it in a pinch

[jamesmunns]

I will begin implementing this as there have been no objections. Implementation checklist:

• [ ] PR upstream - (EDIT: In progress, see https://github.com/rust-lang/rust/pull/56291)
• [ ] Change docs landing page
• [ ] Update new website links
• [ ] robots.txt the old book location
• [ ] 300 redirects for the old book
• [ ] rename nighly version of the book, with robots.txt

[nickray]

Why do the docs live under docs.r-e.org when docs.r-l.org redirects to doc.r-l.org (which I guess is being copied here)? At least a redirect from doc.r-e.org would make sense :)

[jamesmunns]

@nickray there was a voting issue where we picked the name, IIRC docs beat out doc fairly soundly. I think opening an issue to implement the doc => docs redirect would make sense, @nastevens where should that issue go?

[eldruin]

It has been a while. It would be good to revisit this. Nominating.

[adamgreig]

I'd like to fix this longstanding issue, and propose:

1. We delete the docs repository
   • This only hosts outdated submodules of our other books, which would be replaced by the step below
   • It currently has a CNAME file of docs.rust-embedded.org
   • We need to delete it first because it's not allowed to have multiple repos with the same CNAME file
   • Deleting it means we no longer have outdated copies of the books that require updating separately
2. We set the organisation's github pages URL to docs.rust-embedded.org
   • This means all rust-embedded org github pages will be posted at docs.rust-embedded.org/repo, instead of the current rust-embedded.github.io/repo, unless those repos contain their own CNAME file to specify a custom location
   • Specifically it will mean the book, discovery, embedonomicon, and debugonomicon books will be hosted at docs.rust-embedded.org/book etc, with github providing the redirects from rust-embedded.github.io/book for us
   • I think this is the nicest outcome as it means all the books have good URLs which can be published to from their own repositories with no change to the CI or anything, and no central docs repo
   • It does mean any other rust-embedded repo using gh-pages will end up on docs.rust-embedded.org instead of rust-embedded.github.io; I don't think this is a serious problem and it's still possible to use custom domains for them.
   • We do this by creating a rust-embedded.github.io repository with a CNAME file containing that domain
   • DNS is already set up for that domain to point to github (since it's used for the docs repo above)
3. We move blog and showcase to their own domains, blog.rust-embedded.org and showcase.rust-embedded.org
   • We'll need to set up DNS entries, there's already an old PR for them though
   • Then we add a CNAME file to each that contains the new URL
   • GitHub will automatically sort out redirects for us from rust-embedded.github.io

I note that since this issue was opened, the embedded book has been included in the main Rust bookshelf and is occasionally updated by PRs. This proposal doesn't remove this duplication as I'm not sure what the best way forward is and would like to resolve the other issues first. One option is to have the rust-lang page link to our URL instead, as it does for the CLI and WASM books, another option is to make ours more clearly a "nightly" version or something. Or live with two copies.

Could I get an approval from some other resources team members?

• [x] @adamgreig
• [x] @andre-richter
• [x] @eldruin
• [x] @hargoniX
• [ ] @jamesmunns
• [x] @therealprof

Also pinging @ryankurte about the DNS setup, is there anything blocking getting that PR merged to add the new DNS records?

[ryankurte]

Also pinging @ryankurte about the DNS setup, is there anything blocking getting that PR merged to add the new DNS records?

would that be https://github.com/rust-embedded/rust-embedded-provisioning/pull/17 or another PR to do this? no blockers I just, need a reminder ^_^

[adamgreig]

would that be rust-embedded/rust-embedded-provisioning#17 or another PR to do this? no blockers I just, need a reminder ^_^

Thanks yep, that one indeed!

[therealprof]

@adamgreig I believe there were specific reasons why the book was integrated into the Rust bookshelf in the way it is now but I'm pretty sure we can sort it out this change by talking to the right people.

[steveklabnik]

For the history here, yeah, we have a number of books that are in the "official documentation," and they're integrated in this way. each domain WG was also producing a book, and so we integrated them in the same fashion. it is not 100% clear to me if this is still the right arrangement overall, even amongst the four wgs, the level of "done-ness" varies a lot.

[therealprof]

Removing nominated flag due to decision being made.

[adamgreig]

The URL move above is done now. In the end it turned out simpler to rename docs to rust-embedded.github.io and then change its CI to not build the books, just the landing page and FAQ page.

So, we now have:

• https://docs.rust-embedded.org - docs landing page, generated from rust-embedded.github.io repository
• https://docs.rust-embedded.org/book - book, generated from book repository directly
• https://docs.rust-embedded.org/discovery - discovery, generated from discovery repository directly
• https://docs.rust-embedded.org/embedonomicon - nomicon, generated from embedonomicon repository directly
• https://docs.rust-embedded.org/debugonomicon - other nomicon, generated from debugonomicon repository directly

and:

http://blog.rust-embedded.org http://showcase.rust-embedded.org http://rust-embedded.org

Next up is upgrading CI to use GHA.

[Dirbaio]

Closing this as part of 2024 triage.

URL changes are done, and the above linked repos use GHA.