I think that with this separation we could make the book more like the progit2 book and so make it more easy translate it in various languages.
Keeping the book in the source tree makes it easier to ensure that the book is in sync with the language. Right?
Yes, historically this is the reason.
Can you expand on this a little? What makes it not easy to translate right now, and how would a different repository help?
Well, look at how the ProGit 2 ebook has been translated, there is a repo with the English version can be bifurcated for everyone to want to translate it and become the maintainer of this. I can not think of anything simpler than that.
I’m not a git expert but this can be included in the rust repo as a submodule or something like, cannot ?
It’s feasible that the rust repo could depend on a book repo, always building it. A benefit is the PR wouldn’t need to build stage2 to merge doc fixes, and it would also keep the commit history of Rust to code changes.
I’ve occasionally wished to ignore the various typo commits when looking to see what’s new.
1 Like
Yeah, I think a lot of devs would be happy with not seeing commits about the book when looking at the repo historic.
I'm still not sure why forking the main repo doesn't have the same effect. There's also things like git subtree that could help here too.
I'd like to re-iterate that I care a lot about translations, and I want to make it good for us to do so. But at the same time, I also don't want to do the wrong thing, and have to change it again in the future. As another example: moving the book into an external repository does not improve our ability to translate API docs either. I'd like a comprehensive i18n solution, so that non-English resources are first-class.
With the pace of development today, as well as rollups I don't think the extra building has a significant impact, the way that it did pre-1.0. And, since we want to keep docs and code in synch as much as possible, when something changes, how is the new commit going to pass the build? The circular dependency means that you need to allow a failing builds for either one of them, weakening our overall coverage.
Minor correction:
git subtree never helps with anything.
Ever.
1 Like
... Yeah ... same effect ... but not seems the right way to do that because the translator will not touch most part of the repo.
I also don't like to change ... but sometimes we have to change and in a different repo it would be less pain be constantly changing the book
I don't understand, why the book repo will need a reference to the rust repo ? Isn't it just the inverse ?
All the sample code in the book is verified to compile and run. Therefore changes to the docs must be validated against the latest compiler/libs, and changes to the compiler/libs must be validated against the latest docs.
Is that really needed, since Rust should "theoretically" not introduce breaking changes?
Unstable things have documentation too. And one way of making sure that we don't have breaking changes is to run a lot of tests, of which, the documentation is. So it helps against regressions.
I may be missing something but I have a hard time figuring out where the problem would be if Rust book moved to its own repo. Rust book could use the nightlies to test against? In that case you would not have to depend on the rust repo. The rust repo on the other hand could pull the rust book just for the tests (without the need to render)
I think it would be beneficial too, to move Rust book into it’s own repo (in the Rust organization)
- Easier to fork, less intimidating for people who are not very familiar with the rust repo
- Rendering of the rustbook would not need a complete build of rust (if it can be build with nightly)
- Commits for rust and the docs are separated, better overview of changes
- Commit rights for the rust repo and docs (rust book) can be given separately (I don’t know if it is already possible)
- Translations can just fork the book repo, there is no need to fork the whole rust repo just to translate the rust book…
- …
That’s partly why I began mdBook. But if there is interest from the rust team, I would gladly combine efforts and would be even willing to donate mdbook to the rust community.
2 Likes
FWIW, I’m in favor of moving in this direction to get the doc PRs out of the main PR ‘feed’. The complications are in CI and packaging, they are surmountable, but these are areas where the team is stretched thin and has a hard time offloading the work to the community.
A non-trivial percentage of our docs are permanently tied to the source code, though: the API docs. What’s the i18n solution for that?
1 Like
Let's do one thing at the time 
The rust book is a lot easier to begin with.
The API docs are indeed a lot trickier because they are literally in the source code. I guess one way would be for rustdoc to generate translatable files that could be used to generate the docs in other languages. But it does not seem trivial to implement.
1 Like
+1 to moving the docs out of the main repo (I’ve brought this up a few times in the past, but we’ve been stopped by technical issues, it would be great to solve them).
Also, rustdoc should be moved out, that will take some refactoring, but will otherwise be easier.
1 Like
Thank you every one how commented in this topic, I’m a newbie here and your interaction give me motivation to continue trying to contributing to this great community
What should happen so that this idea can be implemented ?
1 Like
rustbook relies upon rustdoc to do the code example links and run the examples as tests doesn’t it? Does it rely on it for anything else rustbook would have to implement before it could be excised?
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.