-
Notifications
You must be signed in to change notification settings - Fork 98
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Decision: Where should the embedded books live? #257
Comments
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:
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:
|
I will begin implementing this as there have been no objections. Implementation checklist:
|
Why do the docs live under |
@nickray there was a voting issue where we picked the name, IIRC |
Initial addition of the Embedded Rust Book This PR adds the Embedded Rust Book to the bookshelf as a submodule, and adds text for the bookshelf page. I have added a new section after "Master Rust" called "Specialize Rust", with the plan that future domain WG books can also reside here. This now extends the titles down to H3, where formerly only H1 and H2 were used. The added submodule tracks the master branch of the Embedded WG repo. If there are additional steps necessary to make this work in CI (perhaps adding this to `src/ci/docker/x86_64-gnu-tools/checktools.sh:32` or so?), please let me know. CC @steveklabnik @japaric Also CC issue rust-embedded/wg#257
It has been a while. It would be good to revisit this. Nominating. |
I'd like to fix this longstanding issue, and propose:
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? |
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 So, we now have:
and: http://blog.rust-embedded.org Next up is upgrading CI to use GHA. |
Closing 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:
The text was updated successfully, but these errors were encountered: