Shouldn't the book be in a separate repo?

tuco · 2015-10-04T14:33:07.128Z

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.

eminence · 2015-10-04T17:01:17.463Z

Keeping the book in the source tree makes it easier to ensure that the book is in sync with the language. Right?

steveklabnik · 2015-10-04T17:15:03.734Z

Yes, historically this is the reason.

tuco:

so make it more easy translate it in various languages.

Can you expand on this a little? What makes it not easy to translate right now, and how would a different repository help?

tuco · 2015-10-04T20:05:33.121Z

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 ?

seanmonstar · 2015-10-04T20:46:09.618Z

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.

tuco · 2015-10-04T21:22:58.855Z

seanmonstar:

I’ve occasionally wished to ignore the various typo commits when looking to see what’s new.

Yeah, I think a lot of devs would be happy with not seeing commits about the book when looking at the repo historic.

steveklabnik · 2015-10-04T23:40:03.542Z

tuco:

I can not think of anything simpler than that.

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.

seanmonstar:

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.

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.

Gankro · 2015-10-05T02:23:55.380Z

Minor correction:

git subtree never helps with anything.

Ever.

tuco · 2015-10-05T03:10:15.029Z

steveklabnik:

I’m still not sure why forking the main repo doe

… Yeah … same effect … but not seems the right way to do that because the translator will not touch most part of the repo.

steveklabnik:

and have to change it again in the future

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

steveklabnik:

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.

I don’t understand, why the book repo will need a reference to the rust repo ? Isn’t it just the inverse ?

Gankro · 2015-10-05T12:29:14.940Z

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.

Azerupi · 2015-10-05T14:06:56.570Z

Gankro:

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?

steveklabnik · 2015-10-05T14:22:24.015Z

Azerupi:

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.

Azerupi · 2015-10-05T15:47:47.322Z

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.

brson · 2015-10-06T00:10:23.046Z

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.

Gankro · 2015-10-06T00:43:53.220Z

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?

Azerupi · 2015-10-06T10:57:06.726Z

Gankro:

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?

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.

nrc · 2015-10-06T19:16:45.316Z

+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.

tuco · 2015-10-07T16:27:42.241Z

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 ?

mdinger · 2015-10-08T22:34:01.585Z

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?

system · 2019-03-25T08:25:15.880Z

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.