RFC: Custom logo/favicon command-line flags

[ojeda]

Add new command-line flags to rustdoc to specify a file to be used as the logo and/or favicon. The file(s) will be copied to the generated documentation directory and relative paths will be computed to point to the resource from within the generated HTML.

[ssokolow]

Wouldn't it make more sense to do it via a configuration file (or an attribute along the lines of #![doc_logo="path"] next to the top-level module documentation), similar to the PROJECT_LOGO key in a Doxygen Doxyfile or html_theme_options['logo'] for Sphinx's Alabaster theme?

Doing it via command-line flags would needlessly add incentive to wrap otherwise perfectly good built-in Cargo commands in something like just or cargo make or a shell script to compensate for command-line arguments being better suited to transient configuration.

(Doing it via command-line flags also reminds me of how fragile and out-of-band Sphinx's API documentation generation for Python is, since it was developed to replace an existing "maintain Python 2.x's manual in LaTeX" workflow rather than a more JavaDoc/Doxygen/rustdoc-esque approach.)

[Aloso]

🖼️ Rendered

[ssokolow]

Thanks. When I wrote my previous comment, the lack of a "Rendered" link left me forgetting to manually go read the RFC.

Most of the RFC, I agree with as motivation to have alternatives to html_logo_url and html_favicon_url that behave as described. However, I still disagree on arguing that a command-line argument is the proper solution.

I think that the two halves should be discussed separately:

1. One discussion for fixing html_logo_url and html_favicon_url without changing the nature of the API. (Maybe do what was done with Error::description and Error::cause and keep them around but deprecate them in favour of something like html_logo and html_favicon which behave as suggested here? That way, the _url suffix could naturally imply "a literal URL as opposed to a path that will be fixed up".)
2. Another discussion for what's appropriate to expose as command-line overrides. I didn't look at it exhaustively, but a quick skim through the rustdoc --help output seems to suggest that, currently, it's limited to stuff that can't be specified via attributes... often stuff that would be specified via Cargo.toml and passed to rustc or rustdoc by Cargo in the common case. (eg. --crate-type and --extern)

As for the "For projects with many small crates" argument, I'd want to see a proposal for how this is going to be integrated into the existing tooling so it doesn't just wind up as something like "Set package.metadata.docs.rs.rustdoc-args and leave local cargo doc runs to fend for themselves".

(eg. What about if one of these crates is pulled into a project, independent of the rest of the repo, like with ignore or walkdir or regex, and then cargo doc gets run? What should happen in that situation?)

Sure, there could be Cargo.toml fields that get implemented via rustdoc command-line arguments that Cargo fills, but I think the primary discussion should be around how Cargo-based builds are intended to use them.

[ojeda]

Wouldn't it make more sense to do it via a configuration file

Possibly (see "Future possibilities"). Since there are already other similar command-line flags (e.g. the playground URL), this seemed closest to existing practice.

Both should be fine for my use case, but I wanted to focus this RFC on the custom logo issue, not a potential config file.

A config file might be problematic in some edge cases (e.g. a user needs to change the logo for different crates in the same folder) and there is always the question of defining how paths inside the file are resolved.

In any case, one does not necessarily preclude the other (indeed, someone may argue to accept a @file argument with flags, or to be consistent with rustc, etc.).

(or an attribute along the lines of #![doc_logo="path"] next to the top-level module documentation)

This would not solve the second set of issues (see "Motivation" and "Rationale and alternatives"), i.e. that one needs to put the attribute in every single crate and that one may want to do it for core etc.

Doing it via command-line flags would needlessly add incentive to wrap otherwise perfectly good built-in Cargo commands in something like just or cargo make or a shell script to compensate for command-line arguments being better suited to transient configuration.

Cargo-built projects should definitely have a better way to set a custom logo too -- in particular for the workspace case to tweak it for all crates at once. One could argue to have this in Cargo.toml if rustdoc learns the flags (in this world view, it could do so for other things too, e.g. --extend-css). A rustdoc config file could handle it if it is searched for up the tree.

(Doing it via command-line flags also reminds me of how fragile and out-of-band Sphinx's API documentation generation for Python is, since it was developed to replace an existing "maintain Python 2.x's manual in LaTeX" workflow rather than a more JavaDoc/Doxygen/rustdoc-esque approach.)

Command-line flags and config files have different strengths. Config files are more elegant in the cases where they fit the model one has. Command-line flags, however, are more flexible in general and can also double as a config file.

[ssokolow]

Both should be fine for my use case, but I wanted to focus this RFC on the custom logo issue, not a potential config file.

However, you are mashing together two issues:

1. There is an existing mechanism with a major flaw
2. The interface to access that mechanism doesn't fit your use-case.

For anyone who fits the common case otherwise, you're effectively forcing people not in your situation to choose which of two options is the lesser of two evils. (Do I use just or cargo make or make to request that Cargo fix up the logo paths or do I use them to fix them up after running cargo doc?)

Cargo-built projects should definitely have a better way to set a custom logo too -- in particular for the workspace case to tweak it for all crates at once. One could argue to have this in Cargo.toml if rustdoc learns the flags (in this world view, it could do so for other things too, e.g. --extend-css)

True, but we don't need to get ahead of ourselves, since implying too much change now can incentivize postpone-ing... if for no other reason than lack of time to properly consider a larger proposal.

We already have flawed attributes for this in html_logo_url and html_favicon_url and the lack of things like --extend-css didn't prevent Cargo from mapping [dependencies] to --extern.

As I see it, a simple way to implement something like this incrementally could be:

1. Implement the new ones as attributes so they don't pose a footgun from people assuming that the old html_*_url are alternatively named but otherwise semantically identical to the new Cargo.toml/command-line versions.
2. Use the same precedence behaviour used for anything else that can be configured both through attributes and externally.
3. Decide on a bare minimum Cargo.toml amendment that doesn't specify every rustdoc argument, but does specify a consistent plan for how any future additions should fit in without introducing inconsistencies.
4. Specify Cargo.toml keys for the new logo and favicon settings to be introduced at the same time as the CLI arguments to ensure the CLI arguments are seen as plumbing, not porcelain, in git terminology. (i.e. Stabilized APIs that you're welcome to use for things like Bazel integration, but most users aren't supposed to be drawn to.)

Command-line flags and config files have different strengths. Config files are more elegant in the cases where they fit the model one has. Command-line flags, however, are more flexible in general and can also double as a config file.

I firmly believe that command-line flags are for two things:

1. Transient settings
2. As a form of IPC between the recipient and some external configuration generator/parser (eg. Cargo generating --extern entries for rustc from Cargo.toml)

For the common-case use of Rust, only option 1 is typically exposed to the user, with option 2 being hidden behind Cargo.toml keys or pushed aside into something like ~/.cargo/config where it's accepted as a rough edge but still given an official way to make the change permanently and then not think about it.

A big part of the common-case Rust experience comes from recognizing that raw command-line arguments are the raw pointers (*const and *mut) of defining how to invoke a subprocess. We shouldn't be encouraging common-case users to use more unsafe and we shouldn't be encouraging common-case users to interact with raw command-line arguments for non-transient uses more than necessary.

(Plus, it just feels clunkier... like it's moving the core Rust experience closer to what you get when you resort to adding a Makefile or justfile to work around things like Cargo's lack of support for some kind of post-build.rs.)

[ojeda]

1. One discussion for fixing html_logo_url and html_favicon_url without changing the nature of the API. (Maybe do what was done with Error::description and Error::cause and keep them around but deprecate them in favour of something like html_logo and html_favicon which behave as suggested here? That way, the _url suffix could naturally imply "a literal URL as opposed to a path that will be fixed up".)

This is fine and useful for many users, but note that it does not solve the second set of issues and suffers from the complexity of how to resolve paths.

2. Another discussion for what's appropriate to expose as command-line overrides. I didn't look at it exhaustively, but a quick skim through the rustdoc --help output seems to suggest that, currently, it's limited to stuff that can't be specified via attributes... often stuff that would be specified via Cargo.toml and passed to rustc or rustdoc by Cargo in the common case. (eg. --crate-type and --extern)

This is incorrect. As mentioned above, the playground URL has both an attribute and a flag (or two -- but one does not seem documented).

As for the "For projects with many small crates" argument, I'd want to see a proposal for how this is going to be integrated into the existing tooling so it doesn't just wind up as something like "Set package.metadata.docs.rs.rustdoc-args and leave local cargo doc runs to fend for themselves".

(eg. What about if one of these crates is pulled into a project, independent of the rest of the repo, like with ignore or walkdir or regex, and then cargo doc gets run? What should happen in that situation?)

Can you elaborate? Cargo can take advantage of the new flags or not, depending on how it wants to handle it, but I do not see the relation to the "projects with many small crates" bit.

Sure, there could be Cargo.toml fields that get implemented via rustdoc command-line arguments that Cargo fills,

Yes, this is one of the possibilities I was suggesting above.

but I think the primary discussion should be around how Cargo-based builds are intended to use them.

Cargo-based builds can use them just as they use any of the other flags. It is interesting to discuss what would be the best solution for Cargo-built projects (e.g. Cargo.toml vs. config file for rustdoc vs. ...), but I think that is out of scope.

Now, if the rustdoc team is planning to migrate to a config file anyway, and prefers to avoid new flags, then this can wait until then, of course. Is that the case?

[ssokolow]

This is fine and useful for many users, but note that it does not solve the second set of issues

But, as I said, they're two separate sub-issues that should be solved independently, so that you don't force people who want the fix to accept what they see as a feature regression.

and suffers from the complexity of how to resolve paths.

How is it more difficult than reusing whatever machinery #[path = "foo.rs"] (on mod) and std::include_str!("foo") use to resolve paths relative to the current file?

That seems like the most intuitive thing to do.

This is incorrect. As mentioned above, the playground URL has both an attribute and a flag (or two -- but one does not seem documented).

Point taken.

Can you elaborate? Cargo can take advantage of the new flags or not, depending on how it wants to handle it, but I do not see the relation to the "projects with many small crates" bit.

"Cargo can take advantage of the new flags or not, depending on how it wants to handle it" is the problem.

This isn't C or C++, where people are used to just throwing in whatever new feature they need without considering the effect on the experience as a whole.

I don't want this to become "My problem has been fixed. I wash my hands of it. I'll leave you to figure out how to keep this from encouraging the most common-case situation to get uglier and messier."

but I think that is out of scope.

That's the problem.

What you're asking for is a less overtly problematic analogue to "Here's a patch to implement syscalls for streaming TCP-to-disk file read/write. Because I'm using this in a single-user, airgapped-LAN configuration and I run my software as root, hooking it up to filesystem permission checks is out of scope."

You're saying "give me what my niche use-case needs, and I leave it up to others to figure out the rest if they want to avoid regressing the common-case experience". (Which is what would happen if the choice is between "broken path/url semantics that are consistent with the rest of the design" and "fixed path/url semantics that encourage people to use hacky ways to invoke them".)

[ojeda]

However, you are mashing together two issues:

No, I am not. I have a need for this use case, which is currently not supported, and I wrote an RFC that would solve the issue with the minimum changes required on the Rust side. There are alternative solutions, which the RFC mentions. That is all there is to it. It is on the rustdoc team to decide which course would be best depending on what they are planning to do with current flags / config files etc.

1. There is an existing mechanism with a major flaw

I would not say it is a "major flaw". The use case was probably not considered, specially given how it works (copy-paste of the content) and the name of the attributes (url).

2. The interface to access that mechanism doesn't fit your use-case.

No, the feature is simply not present. See above.

For anyone who fits the common case otherwise, you're effectively forcing people not in your situation to choose which of two options is the lesser of two evils. (Do I use just or cargo make or make to request that Cargo fix up the logo paths or do I use them to fix them up after running cargo doc?)

No one is "forced" to do anything. Existing users remain the same, and those that could have taken advantage of this feature are already using a workaround. If this gets introduced, some users will be able to use the feature now instead of using a workaround.

Now, you are concerned about Cargo users using a Makefile to call Cargo, but they already need that for other flags or for the workaround mentioned in the RFC. I also already agreed that there could be a better way to handle the logo for Cargo-based projects in general, and in fact, someone could use this RFC as rationale for an RFC on config files for rustdoc.

[...]

I am sorry, but I skip the rest of your comment because I believe how you feel about command-line flags, other builds systems, unsafe analogies, etc. is really going out of topic.

[ssokolow]

I am sorry, but I skip the rest of your comment because I believe how you feel about command-line flags, other builds systems, unsafe analogies, etc. is really going out of topic.

I believe insisting on a placing a high emphasis on building and preserving a coherent experience for people using Cargo as their primary interface to the build tooling is a very significant part of what led Rust to the place it is today, so I'll leave it up to others to decide which one of us is off-topic before saying anything more.

If I'm wrong, I'll correct myself. If I'm not, then it's not productive to continue talking at someone who's skipping over my points and I'll leave it to someone with more clout to re-state them.

[ojeda]

But, as I said, they're two separate sub-issues that should be solved independently, so that you don't force people who want the fix to accept what they see as a feature regression.

Please see my other reply about this.

How is it more difficult than reusing whatever machinery #[path = "foo.rs"] (on mod) and std::include_str!("foo") use to resolve paths relative to the current file?

That is fine, but the point was that you have to specify it. Moreover, in the config file case, it is not even Rust code.

This isn't C or C++, where people are used to just throwing in whatever new feature they need without considering the effect on the experience as a whole.

I am unsure what you are thinking about, but C/C++ do not do that. In fact, at times the discussions feel endless. But it does not matter, it is off-topic.

I don't want this to become "My problem has been fixed. I wash my hands of it. I'll leave you to figure out how to keep this from encouraging the most common-case situation to get uglier and messier."

What you're asking for is a less overtly problematic analogue to "Here's a patch to implement syscalls for streaming TCP-to-disk file read/write. Because I'm using this in a single-user, airgapped-LAN configuration and I run my software as root, hooking it up to filesystem permission checks is out of scope."

You're saying "give me what my niche use-case needs, and I leave it up to others to figure out the rest if they want to avoid regressing the common-case experience". (Which is what would happen if the choice is between "broken path/url semantics that are consistent with the rest of the design" and "fixed path/url semantics that encourage people to use hacky ways to invoke them".)

Nobody is "washing their hands", and I request that you stop suggesting otherwise. The RFC got written precisely because I am trying to get this done properly upstream. I could also have ignored this completely and simply use a workaround. In fact, I am starting to think that would have been better.

And it is "Request For Comments", not "I want this and only this and I will not entertain anything else so please just do what I say". In fact, I already said that both solutions (config file or flags) would be fine for my use case. Disagreeing with your opinion of tackling here the general problem of config files etc. does not mean others are lazy or washing their hands.

[ssokolow]

OK, Fair. I admit I was getting a bit un-civil in my frustration and, in hindsight, I should have, at minimum, addressed that differently.

I still think that one of the things that has helped Rust to attract the interest it's receiving is an emphasis on ensuring that the Cargo workflow moves toward a more polished, coherent experience... and I think exposing less footgun-y path handling for favicons and logos in rustdoc without exposing it in a way that can be accessed by invoking a bare cargo doc is moving away from that goal.

I could see your proposal being OK on the condition that it's not API-stabilized and allowed to be used outside of nightly until after a means of using it from a bare cargo doc has been laid down too.

[Mark-Simulacrum]

Given that relative paths are presumably nearly-always broken in the existing URL attributes, does it seem viable to change the meaning of a relative path in those attributes to mean "copy this file in", similar to the CLI flags proposed here?

In general, I at least would prefer to avoid rustdoc (and rustc) growing many flags that are intended to be close mappings onto crate-level attributes, and would love to see -Zcrate-attr stabilized instead of that -- I imagine a compiler MCP proposing its stabilization (perhaps initially limited to attributes that don't need more than key/value pairs) may be a good idea there.

I don't think it makes sense to block adding this feature on support for Cargo to pass these flags down or rustdoc configuration files -- those seem like potentially reasonable enhancements, but are also addable after the fact, right?

[ssokolow]

My two main concerns there are:

1. It doesn't feel in line with all the care the Rust teams put into backwards compatibility.

2. They end in _url, not _path or neither, which tends to imply the current semantics, all the way up to specifying an absolute https://... URL to another server if that happens to be what you want.

   I'm reminded of the distinction Django draws between the STATIC_ROOT and STATIC_URL or MEDIA_ROOT and MEDIA_URL configuration variables. (_ROOT is the root as seen by the "gather static files" task or the file/image fields in your database-schema server and _URL is the base that you effectively Path::join your static asset paths onto when rendering templates for the client.

[ojeda]

Given that relative paths are presumably nearly-always broken in the existing URL attributes, does it seem viable to change the meaning of a relative path in those attributes to mean "copy this file in", similar to the CLI flags proposed here?

In general, I at least would prefer to avoid rustdoc (and rustc) growing many flags that are intended to be close mappings onto crate-level attributes, and would love to see -Zcrate-attr stabilized instead of that -- I imagine a compiler MCP proposing its stabilization (perhaps initially limited to attributes that don't need more than key/value pairs) may be a good idea there.

Definitely, if stabilization of -Zcrate-attr is an option, then that plus attributes handling both cases would work.

In fact, that is what I initially tried before I noticed that in sub-folders the path was not being adjusted. So I think it is reasonable users could expect that.

I don't think it makes sense to block adding this feature on support for Cargo to pass these flags down or rustdoc configuration files -- those seem like potentially reasonable enhancements, but are also addable after the fact, right?

This is what I would have thought, yeah. Though it is also true that, if we get config files eventually, the flags could be redundant.

[ojeda]

OK, Fair. I admit I was getting a bit un-civil in my frustration and, in hindsight, I should have, at minimum, addressed that differently.

No worries, all good!

[ojeda]

Recent changes to the HTML output (rust-lang/rust#115948) broke our workaround for this. It has made it harder to workaround too, since now the Rust logo is not there for non-Rust crates, which in turn means we lose the relative paths computed for it.

It would be nice to have a supported way to bundle a logo file and (most importantly) generate the relative paths to it (even if it is not flags like in this RFC). It would let us remove our workaround and thus would avoid future changes on our side. It will be needed to establish a minimum Rust version in the kernel, eventually.

[Nemo157]

Ah, I see for some reason there was no link to the other RFC that overlaps this one: #3397, by changing #![doc(html_favicon_url)] etc. to handle local paths automatically they could also be used through the CLI with -Zcrate-attr (and potentially have stable CLI flags added that cover both local and remote variations, which may be a small enough change to just FCP).

[ojeda]

Thanks @Nemo157! Yeah, in that RFC, this:

There are two options that will be impacted by this RFC: the favicon and logo that you can respectively set through:

#![doc(html_favicon_url = "some_path", html_logo_url = "some_other_path")]

They will follow the same rule as for other images: if this is a local path, the local file will be copied and the paths to it will be rewritten.

would seem to solve our use case -- if I understand correctly, it is essentially what @Mark-Simulacrum suggested above. It would still require us to use -Zcrate-attr, but it would be much better than the workaround that we have now.

Perhaps that part of the RFC could be split so that it is easier to stabilize? Then #3397 would be easier to get in too.

Otherwise, @ssokolow's suggestion of adding html_*_path versions instead looks good too.