Support generating all docs, introduce doc_cfg and doc_all

[ojeda]

See individual commits for details.

See #442 for more details.

[nbdd0121]

Any reason not to enable all docs?

[ojeda]

What do you mean?

[nbdd0121]

I think we should enable all docs for rustdoc target and not have rustdoc-all.

[ojeda]

I thought about that too (to simplify), but on the other hand, supporting custom docs is very easy, so I thought it was nice to keep it.

e.g. imagine a Linux distribution packaging the docs for a given kernel they provide.

We could also do further things for the custom ones, like a smaller banner when customized for a particular config (including a link to it, etc.).

[ojeda]

I mean, I am not saying it will be used a lot, but on the other hand, people may actually use it if we have it (i.e. the kind of thing nobody will ask about if it is not there, but may end up being used if it is there).

[ojeda]

Another use case is generating the docs faster when you are developing (because typically one only cares about the current .config, e.g. when working in a particular subsystem); while rustdoc-all is only intended for the bot that will generate the ones for kernel.org which would take more time.

[nbdd0121]

Or it could be argued that people may use it because it is there, while they shouldn't be using it and should use rustdoc-all instead.

I would say documenting all items should be the default and would better occupy the name rustdoc, and if people want a trimmed down version it should be a different target.

Another use case is generating the docs faster when you are developing (because typically one only cares about the current .config); while rustdoc-all is only intended for the bot that will generate the ones for kernel.org which would take more time.

Well, that's not really a convincing argument. Kernel crate docs would only be regenerated if kernel crate is changed, so for driver devs wouldn't trigger a re-generation for the docs. Doc generation also does not require borrow checking or code generation, so it is much faster than compilation.

Devs should be able to look into all documentations rather than just the ones being used; e.g. they may forget to add a few CONFIG dependencies and then wouldn't notice that some Rust binding exists.

[ojeda]

I would say documenting all items should be the default and would better occupy the name rustdoc, and if people want a trimmed down version it should be a different target.

As a subsystem developer, if I am generating the docs to check my changes, then I prefer the trimmed down version; i.e. there is not much use about many other subsystems (including things from other architectures) that would be around otherwise.

Basically, I see two use cases:

• I want to explore the docs, i.e. I want to see everything: I go to kernel.org (or generate them myself).
• I want to check my changes, i.e. I only need to see what I changed: I generate them locally because nobody has them pregenerated anyway.

Doc generation also does not require borrow checking or code generation, so it is much faster than compilation.

Yes, but if Rust grows in the kernel, we will have a lot of things. Being able to skip entire subsystems and architectures can make quite a difference. It is like building allmodconfig vs. your particular config.

they may forget to add a few CONFIG dependencies and then wouldn't notice that some Rust binding exists.

This is fair, it could potentially cause some confusion -- perhaps not in the case you mention (i.e. a driver developer knows the bindings/configs they need and they will notice otherwise), but for things like optional functionality (e.g. utility functions that for some reason are gated) that they may not notice if they rely on their own docs for exploration. Hmm...

[ojeda]

It is not particularly important anyway, so we can always prioritize simplicity for the moment.

[ojeda]

Let's go with the simplest way. I have kept this in an issue in case someone needs the feature in the future: #447