Possible nightly rustdoc doc generation time / size regression

[piaoyh]

I published my crate to crates.io, but I found the server does not generate documentation properly. My crate is cryptocol and its link is https://docs.rs/cryptocol/0.8.5/cryptocol/. However, the webpage https://docs.rs/cryptocol/0.8.5/cryptocol/number/big_uint/struct.BigUInt.html#struct.BigUInt is failed to be generated. At the site, rust-lang/docs.rs#2676 , it is recommended to toss the issue here because it is considered that the reason is related to that fact that cargo +nightly docs does not work properly.

I tried this code:

cargo +nightly docs

I expected to see this happen: All the webpages will be generated properly. Especially, /home/youngho/shared/rust-target/doc/cryptocol/number/big_uint/struct.BigUInt.html should be properly generated. So, for offline test, when I execute cargo +nightly docs, it should generate all the webpages fine as executing cargo doc.

Instead, this happened: For offline test, when I execute cargo +nightly docs, it keeps running but never ends. It looks that the cargo falls into infinite loop. However, when I execute cargo doc, it generated all the webpages fine.

Meta

rustc --version --verbose:

cargo 1.83.0 (5ffbef321 2024-10-29)
rustc 1.83.0 (90b35a623 2024-11-26)
rustdoc 1.83.0 (90b35a623 2024-11-26)

$ rustc --version --verbose
rustc 1.83.0 (90b35a623 2024-11-26)
binary: rustc
commit-hash: 90b35a6239c3d8bdabc530a6a0816f7ff89a0aaf
commit-date: 2024-11-26
host: x86_64-unknown-linux-gnu
release: 1.83.0
LLVM version: 19.1.1

I feel it strange about why it takes so irrationally long and generates irrationally big size of file. (Somebody said that if you wait for an hour, it generates 60 MB-sized struct.BigUInt.html, but I haven't wait for that long time.) BigUInt.rs of version 0.8.4 is 2.9 MB in size while BigUInt.rs of version 0.8.5 is 4.0 MB. The change (1.1 MB) in size makes huge difference. There must be a size threshold that cargo cannot deal with files.

backtrace

[workingjubilee]

@piaoyh does this pathological behavior occur if you remove everything from the crate except BigUInt?

[piaoyh]

@workingjubilee Sorry for late reply because of time difference and I have to work at daytime.

If I remove everything from my crate except BigUInt and execute cargo +nightly docs, it reports a lot of errors because BigUInt is dependent other structs in number module. So, I couldn't remove everything from the crate except BigUInt.

Instead, I removed all other modules from my crate except the module number and executed cargo +nightly docs. I found that the result was the same. It seemed that it fell into infinite loop. However, if I execute cargo doc, it works fine.

[piaoyh]

I don't know whether the following helps you or not.
I found three things:
When I execute cargo doc, it works fine.
However, when I execute cargo docs, it seems to fall into infinite loop.
And, when I execute cargo +nightly docs, it also seems to fall into infinite loop.

So, it seems cargo works fine with the argument doc while cargo does not work with the argument docs with/without the argument +nightly.

Usually, when I test documentation, I have always used only cargo doc because I didn't know that there was the argument docs. Actually, when I execute cargo, it does not show the description about docs.

When I was asked to try to execute cargo +nightly docs, I thought that there was the argument docs only for the argument +nightly which is nightly version. And I suddenly suspected that there might be the argument docs for normal version as well though cargo hides the argument docs for help for users for unknown reason. Yet, I don't know what the argument docs means or is for. Maybe it is only for cargo developers for test. That's why the argument docs is hidden from users at cargo help.

$ cargo
Rust's package manager

Usage: cargo [+toolchain] [OPTIONS] [COMMAND]
cargo [+toolchain] [OPTIONS] -Zscript <MANIFEST_RS> [ARGS]...

Options:
-V, --version
Print version info and exit
--list
List installed commands
--explain
Provide a detailed explanation of a rustc error message
-v, --verbose...
Use verbose output (-vv very verbose/build.rs output)
-q, --quiet
Do not print cargo log messages
--color
Coloring: auto, always, never
-C
Change to DIRECTORY before doing anything (nightly-only)
--locked
Assert that Cargo.lock will remain unchanged
--offline
Run without accessing the network
--frozen
Equivalent to specifying both --locked and --offline
--config <KEY=VALUE|PATH>
Override a configuration value
-Z
Unstable (nightly-only) flags to Cargo, see 'cargo -Z help' for
details
-h, --help
Print help

Commands:
build, b Compile the current package
check, c Analyze the current package and report errors, but don't build object files
clean Remove the target directory
doc, d Build this package's and its dependencies' documentation
new Create a new cargo package
init Create a new cargo package in an existing directory
add Add dependencies to a manifest file
remove Remove dependencies from a manifest file
run, r Run a binary or example of the local package
test, t Run the tests
bench Run the benchmarks
update Update dependencies listed in Cargo.lock
search Search registry for crates
publish Package and upload this package to the registry
install Install a Rust binary
uninstall Uninstall a Rust binary
... See all commands with --list

See 'cargo help ' for more information on a specific command.

[syphar]

To clarify the comment above for the people debugging this: I assume @piaoyh is not talking about cargo docs as command, but cargo docs-rs, which is coming from this package which emulates how docs.rs builds the docs.

[piaoyh]

No, I was talking about cargo docs, NOT cargo docs-rs.
I tested with the command cargo docs.
Actually, I don't know what is the difference between cargo docs and cargo docs-rs exactly. I just let you know what I got from execution of the command cargo docs. I thought that it would help you.

I tested more.

• The cargo docs-rs gives the following error message:
  error: the -Z flag is only accepted on the nightly channel of Cargo, but this is the stable channel
  See https://doc.rust-lang.org/book/appendix-07-nightly-rust.html for more information about Rust release channels.
• The cargo +nightly docs-rs seems to work fine. It did not fall into the infinite loop. I generates struct.BigUInt.html successfully. Its size is 4.6 MB.

merry Christmas to all.

[piaoyh]

I dramatically reduced the code of my crate for test but still cargo +nightly docs ran endlessly.

What am I supposed to test to find why docs.rs does not show documentation of my crate cryptocol correctly? cargo +nightly docs-rs or cargo +nightly docs?

cargo docs-rs gives me error.
cargo +nightly docs-rs has worked fine even before I reduced my code for test.
cargo +nightly docs ran endlessly.

[piaoyh]

I thought that cargo +nightly docs is related with publishing crates at crates.io and docs.rs. But while I was reading carefully the above comments again, I found syphar's comment. As syphar said, cargo docs-rs is coming from this package which emulates how docs.rs builds the docs.

Then, does it mean cargo +nightly docs-rs is related with how docs.rs builds the docs rather than cargo +nightly docs?

If so, my question is why the webserver docs.rs fails in building struct.BigUInt.html though cargo +nightly docs-rs works fine and generates struct.BigUInt.html well at my local computer. The size of the generated struct.BigUInt.html is 8.5MB at my local computer. And the source file of big_uint.rs has 58046 lines and its size is 2.7 MB.

What is the limit size of each source file for publishing crate? Is my source code too big or does cargo +nightly docs-rs that works at the webserver docs.rs have a bug?

Can anyone answer me?