cargo-doc: enable using --html-in-header and other rustdoc flags

[SimonSapin]

Currently I see no way of doing this. Perhaps it should be Cargo.toml configuration keys?

[alexcrichton]

We've tried avoiding just exposing the entire CLI of a tool as it makes deterministic builds nearly impossible. What exactly do you have in mind for these sorts of flags? Things like html-in-header we could certainly add support for!

[SimonSapin]

Adding a custom stylesheet, or a githuh ribbon

[alexcrichton]

Oh ok, you mentioned that there may be other rustdoc flags you were interested in, but is --html-in-header the only one currently necessary?

[SimonSapin]

Looking at --help now… Potentially any flag with "html" or "markdown" in the name.

[SimonSapin]

Though perhaps these would be better in a configuration file than as command line flags in the first place.

[steveklabnik]

We've been talking about just adding a frontmatter, I forget the issue #. That'd probably work too.

[SimonSapin]

@steveklabnik What’s a frontmatter?

[steveklabnik]

see https://github.com/rust-lang/rust/issues/16178

I would suggest that this be closed in favor of that.

[SimonSapin]

If understand correctly, rust-lang/rust#16178 is about adding metadata to a single Markdown file. I’d like to add stuff (e.g. a CSS stylesheet) to every documentation page of a given project, including pages generated by rustdoc for a Rust item.

[steveklabnik]

I guess I'd expect that ticket to cover some sort of 'layout' as well, which would let you apply such things globally. that might be wrong, but rustdoc is the right place for this, not cargo

[thehydroimpulse]

Yes, the idea is that the frontmatter will lead rustdoc to support layouts.

So you could have:

---
layout: main
title: "Foo bar"
keywords: ["foobar", "123"]
---

And

---
layout: guide
title: "Foo bar"
keywords: ["foobar", "123"]
---

However, this doesn't exactly solve the auto-generating API docs. We could introduce a doc.json configuration file (toml would be better to be consistent, but I'm not sure if we could have that kind of dependency) to have more advanced options. Or perhaps it should be merged in the Cargo.toml?

...
[doc]
logo = "http://.../logo.png"
stylesheets = ["doc/index.css", "doc/base/index.css"]

Not sure if the complexity is worth it, but it could come in handy at times.

[SimonSapin]

Whatever a "layout" is, I’d still want a default one project-wide, that I wouldn’t have to specify in every file.

[steveklabnik]

Of course.

[alexcrichton]

I tend to agree that I would rather this be configuration in-source rather than command lines to rustdoc. The tool at fault here is arguably rustdoc rather than cargo. If the documentation doesn't look good unless you pass a set of flags, then the documentation shouldn't be able to be built without those sets of flags.

We may want to extend the crate-level #![doc] attribute which already has other metadata-ish things. I don't think that this bug is precisely a dupe of rust-lang/rust#16178, but rather it needs a rust bug saying that the --html-in-header flag should be a crate attribute instead (likely).

[kornelski]

:+1: I've ran into this myself while trying to move from Makefiles to cargo :(

If the documentation doesn't look good unless you pass a set of flags, then the documentation shouldn't be able to be built without those sets of flags.

This isn't the problem I have. The standard documentation looks good, but has Rust's style, not my project's style.

I'd like to add a custom header, because I want to customize the output and tinker with CSS and HTML, e.g. I hate webfonts, but I don't want to be arguing with you whether webfonts are good for all documentations of all Rust projects everywhere. I just want to hack the output to remove them from my project only.

I don't understand why deterministic builds of documentation are important, even in projects that require deterministic build of binaries. But if it matters, why the solution can't be "don't use unpredictable custom flags" or maybe add --unsafe { --html-before-content foo.html } to cargo ;)

I suppose something like that in Cargo.toml

[profile.doc]
html-before-content = "foo.html"

or

[profile.doc]
rustdoc-flags = "--html-before-content = foo.html"

would be an OK solution.

[drewcrawford]

I landed here trying to implement the workaround in https://github.com/rust-lang/rust/issues/15347 (which is probably going to get closed "behaves correctly" due to the fact that you can pass flags to rustdoc that solve the problem).

Basically, I want to pass, for development purposes,

--no-defaults --passes "collapse-docs" --passes "unindent-comments"

to rustdoc (but not ship those flags to users).

I think cargo should have support for that, either as a high-level --private-docs flag or just let me specify raw rustdoc options like --rustdoc-extra '--no-defaults --passes "collapse-docs" --passes "unindent-comments"'

[Lucretiel]

I know +1 comments are usually frowned upon, but I'd like to re-up this feature request. There's been a lot of discussion about metadata and custom css and so on, but my interest is purely in finding a way to add the "Fork me on Github" snippet to my docs during cargo doc.

[LukeMathWalker]

This is relevant as well when trying to render mathematical formulas in the documentation: the --html-in-header option can be used to include KaTeX to support rendering (see here), but this can generate issues to consumers of the library downstream (see @jturner314's comment in https://github.com/rust-ndarray/ndarray/issues/598) if we can't set it using Cargo.toml.

[m-ou-se]

Maybe it should be an attribute in the rust code, rather than an option in the Cargo.toml, just like #![doc(html_favicon_url = ...)].

[m-ou-se]

By the way, it can already be done using 'html injection' through the html_favicon_url attribute:

#![doc(html_favicon_url = "\">
<link rel=\"stylesheet\" ...>
<script> ... </script>
<meta name=\"")]

:wink:

(Demo: https://docs.rs/horrible-katex-hack/)

[jtdaugherty]

I'm running into this because I want to generate rustdocs for my test code. To do that I'd like to use cargo doc, but I can't pass --cfg test to rustdoc to get the desired result. Is there some other way to accomplish what I want?

[jyn514]

For my sanity: the feature request here is to allow configuring this per-crate in Cargo.toml or as an attribute, cargo already lets you do this globally with RUSTDOCFLAGS or when building your own crate yourself with cargo rustdoc.

[CAD97]

By the way, it can already be done using 'html injection' through the html_favicon_url attribute:

This got "fixed" at some point, and the html_favicon_url value is "properly" escaped in the generated HTML now.

[elichai]

Another option is to set

[build]
rustdocflags = ["--html-in-header", "docs_header.html" ]

in .cargo/config but this messes up dependencies, and requires you to add --no-deps to any cargo doc invocation

[CAD97]

I filed rust-lang/rust#95 to enable the specific case of --html-in-header.