Compatibility of rustdoc output between versions

[infinity0]

I'm trying to figure out a way to include crate docs in the Debian rust packages. cargo doc calls rustdoc which generates:

1. crate-specific files: html and portions of aliases.js and searchindex.js, and
2. general documentation files: i.e. css, js, font files, etc.

One clean way to include this in Debian would be to distribute (1) as its own package, e.g. librust-$crate-doc, that depends on a shared common package librust-doc-common that contains (2).

However this then raises the question, how stable is the data format of (1)? When building (1) we have to use a specific version of rustdoc. When we upgrade rustdoc, we will change (2). Will the newer (2) still be compatible with the older (1)? It would be nice not to have to rebuild all crates whenever we upgrade rustdoc.

(We also have to combine all crates' aliases.js and searchindex.js into one single file, but that is relatively easy to do with dpkg triggers.)

[jyn514]

In general, this is not stable. The CSS and HTML are intertwined, and changing the one requires changing the other. See rust-lang/docs.rs#464 for a similar issue for docs.rs.

[jyn514]

@infinity0 does that answer your question? I'm not sure what we could do here, since it means that e.g. adding a new CSS class and highlighting based on that would break documentation compiled with a different version of rustdoc, and that's not a level of stability I think anyone on the team is willing to commit to.

[jyn514]

What you could do instead is distribute librust-1.38.0-doc-common and have an explicit dependency on that, so you don't have to rebuild all the old crates, they just might not get the latest rustdoc features.

[infinity0]

@jyn514 Thanks for confirming, so I guess the answer is no at this time. :( In Debian we avoid keeping multiple versions of things unless absolutely necessary, so in fact the librust-1.38.0-doc-common would result in rebuilding everything anyways. Part of that process is automated but part of it is not, so it's not ideal at this time. Never mind!