Repository navigation
Decision: Where should the embedded books live? #257
Description
Activity
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.
Anything not in the main rust repo does not get distributed offline.
@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?
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.
That's fair and sort of what I expected, thanks for clarifying!
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.
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/
Hey @rust-embedded/all - if no issues are raised, I would like to go with the following plan:
- Open a PR to the upstream doc repo adding the Embedded Rust Book as a submodule there
- 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"
- Update the new website (not yet public) to point links to the "centralized" copy of the book
- Add a
robots.txtto our copy of the book (https://docs.rust-embedded.org/book/), preventing it from being crawled. - Replace all current pages of https://docs.rust-embedded.org/book/ and children to be 300 redirects to the "centralized copy"
- 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
Reacted by Michael Leonard, Adam Greig, Emil Fresk and ryanI will begin implementing this as there have been no objections. Implementation checklist:
- PR upstream - (EDIT: In progress, see Initial addition of the Embedded Rust Book rust-lang/rust#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
Why do the docs live under
docs.r-e.orgwhendocs.r-l.orgredirects todoc.r-l.org(which I guess is being copied here)? At least a redirect fromdoc.r-e.orgwould make sense :)@nickray there was a voting issue where we picked the name, IIRC
docsbeat outdocfairly soundly. I think opening an issue to implement thedoc=>docsredirect would make sense, @nastevens where should that issue go?Reacted by Nicolas StalderIt has been a while. It would be good to revisit this. Nominating.
I'd like to fix this longstanding issue, and propose:
- We delete the
docsrepository- 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
- 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 currentrust-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, anddebugonomiconbooks will be hosted atdocs.rust-embedded.org/booketc, with github providing the redirects fromrust-embedded.github.io/bookfor 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
docsrepo - It does mean any other rust-embedded repo using gh-pages will end up on
docs.rust-embedded.orginstead ofrust-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.iorepository 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)
- This means all rust-embedded org github pages will be posted at
- 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?
Also pinging @ryankurte about the DNS setup, is there anything blocking getting that PR merged to add the new DNS records?
Reacted by Diego Barrios Romero- We delete the
Also pinging @ryankurte about the DNS setup, is there anything blocking getting that PR merged to add the new DNS records?
would that be rust-embedded/rust-embedded-provisioning#17 or another PR to do this? no blockers I just, need a reminder ^_^
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!
@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.
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.
Removing nominated flag due to decision being made.
The URL move above is done now. In the end it turned out simpler to rename
docstorust-embedded.github.ioand 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.orgNext up is upgrading CI to use GHA.
Reacted by Diego Barrios Romero and ryanClosing this as part of 2024 triage.
URL changes are done, and the above linked repos use GHA.
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:
Cons:
In IRC, we came up with the following possible solutions: