Build rustbook without having to wait 20 min?


#1

Hi, I’m trying to get involved and I thought I would try to see if I could make some small improvements on the Rustbook (engine). Since I am not familiar with how it’s implemented, I try little changes at a time.

But is there a way to build rustbook without having to build everything? At the moment I use:

make docs

But I have to wait 20 minutes before it stops building, and that’s a real blocker. Is there some magic trick to speed up that process?


#2

I don’t know the magic trick to work on rustbook offhand but rustbook is a pretty simple crate so you can probably build it from the command line. If you run make VERBOSE=1 you can see the commands being executed and then copy them for your own use.

In some places the build system supports setting NO_REBUILD=1 to short-circuit the bootstrap, but it almost certainly doesn’t work for rustbook.


#3

Ok thanks!

I will try to figure it out tomorrow if no one else jumps in to save the day until then :wink:

By the way, I have been following the thread about submodules. Is that going to improve such things? Making every crate more isolated and more approachable for new contributors?


#4

@Azerupi With the current set of crates being considered for submodulification it won’t help much, since they are all stable-compatible crates that work on cargo, and are already maintained outside of tree. The frustrating parts of in-tree development (hacking on the compiler especially), will remain frustrating.

It may be possible to move rustbook out of tree and re-add it as a submodule since it’s a pretty simple project, but it currently has dependencies on compiler internals that complicate that prospect. In fact, I believe when we merged rustbook that was part of the plan: we would dump it in-tree to get the book building, but because we aren’t sure about the wisdom of distributing rustbook with rust, would also package it out-of-tree for others to use.

It would be great to fill out rustbook to make it a viable tool for everybody.


#5

A few tips:

I maintain an out-of-tree copy of Rustbook at https://github.com/steveklabnik/rustbook which you can use.

make trpl will invoke the process for just the book. You may or may not want NO_REBUILD=1 as well, to prevent a rebuild. rustbook depends on rustdoc, which depends on rustc, sooo

If you’re just doing some light editing, you can also just run rustdoc on the markdown file directly, It won’t be the same output, can be easy for, for example, checking if a code sample compiles: just rustdoc --test src/doc/trpl/whatever.md.


#6

@brson Thanks for the info!

Is that up to date? And if I make a PR how is that going to be reflected into the rust repo?

This seems to be exactly what I was looking for, thank you soo much :smile:


#7

I try to double check it every week or two. Rustbook doesn’t move that much.

Please submit PRs to the rust repo itself, then I will mirror them out to my mirror.


#8

Good, I have done some simple changes today and made a PR. Mostly changes to the css.

Once I get more familiar with how it works I will try to do more substantial improvements though :blush:

I have seen a PR that removes JQuery dependency should I avoid to use it? I would not want to sabotage someone else’s work :wink: