Skip to content

Latest commit

 

History

History
85 lines (51 loc) · 5.35 KB

0000-custom-logo-favicon-flag.md

File metadata and controls

85 lines (51 loc) · 5.35 KB

Summary

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.

Motivation

Currently, there are two forms of the doc attribute to specify a custom favicon and logo: html_favicon_url and html_logo_url. However, they take the content as-is into all pages. Thus they effectively require an absolute URL/path. In particular, they do not allow to specify a local file and have the system compute the relative path as needed in sub-pages, like it is done in the non-custom case. Therefore, offline usage or publishing under a given path is harder.

A workaround for this is using the non-custom case and replacing the logo and the paths in every HTML file after generation (because the non-custom case generates relative paths to the official logo/favicon). For the favicon case, it is also needed to remove the alternate icon ones. Of course, this sort of hacks can break at any time.

Instead, it would be better to cover this use case properly with a command-line flag to specify a file to the favicon/logo and let rustdoc copy the file(s) and compute the paths as needed.

Another downside of the current html_favicon_url and html_logo_url is that they require changing the source code of the crate. For projects with many small crates (but all built together as part of the same project/workspace), it is boilerplate that needs to be repeated in every crate. Furthermore, projects that have custom builds of the standard library need to modify somehow the source code. Both cases may be worked around via -Zcrate-attr or a temporary copy. However, a command-line flag would be ideal, and would also cover the first issue discussed above.

It can also be argued that the logo/favicon URLs do not really belong with the Rust source code itself, but rather that they are out-of-band configuration/metadata for the documentation (similar to e.g. build/formatting options for Cargo/rustfmt).

Guide-level explanation

The following is written as if it belonged in the "Command-line arguments" section of the rustdoc documentation.

--html-logo

Using this flag looks like this:

$ rustdoc src/lib.rs --html-logo logo.svg

This flag takes an image file which will be used as the custom HTML logo in the rendered documentation. The file will be bundled together with the rest of the files in the output path.

--html-favicon

Using this flag looks like this:

$ rustdoc src/lib.rs --html-favicon favicon.svg

This flag takes an image file which will be used as the custom HTML favicon in the rendered documentation. The file will be bundled together with the rest of the files in the output path.

Reference-level explanation

The file taken by the flags shall be copied as-is into the root output path. It is a hard error if it cannot be copied for any reason (e.g. the file does not exist or cannot be read).

The rendered HTML should point to the file via relative paths, similarly to how it is done in the non-custom case.

If both a command-line flag and the related doc attribute are specified in the crate, the command-line flag takes precedence and a warning is emitted (users should have the ability to "allow" the warning).

Drawbacks

It adds complexity to the command-line interface of rustdoc.

Rationale and alternatives

Not doing this implies users will need to use workarounds like those described in the "Motivation" section. These workarounds are not easy to use, but more importantly, they may break at any point.

An alternative to a command-line flag would be having the functionality as part of the doc attributes in some form. However, while that would address the ability to use a local image file, it would not address the boilerplate issue nor the custom standard library builds (as mentioned in the "Motivation" section).

Prior art

Sphinx's configuration accepts the html_logo and html_favicon options. Both options accept either a URL or a local file (which gets copied into the static files of the generated docs).

Unresolved questions

None.

Future possibilities

The command-line interface could handle the URL case too, possibly via independent flags (e.g. --html-logo-url and --html-favicon-url) in order to avoid the issue of distinguishing URLs from files.

Perhaps this sort of documentation configuration/metadata could be specified in another place, e.g. a configuration file (similar to e.g. build/formatting options for Cargo/rustfmt).