Which artifacts generated by rustdoc must be kept for the static site to function?

help
1

I won't publish my little crate to crates.io, so it's not going to get a nice docs.rs site, but I still want to link to its documentation in the GitHub repository. I figured I can host it using GitHub Pages.

I know I can customize the output directory of cargo doc so that Git sees it with --target-dir. What I don't know is which parts of that are necessary for the generated site to function and which can be safely discarded.

For example, it generates debug and release subdirectories (though, for some reason, they're empty). Can I add them to my .gitignore?

2

You may check out how rand deploy rustdoc HTML on github pages: rand/.github/workflows/gh-pages.yml at master · rust-random/rand · GitHub

2 Likes
3

Your documentation is generated in target/doc. It is standalone, so everything else in your target/ directory can be ignored for hosting the docs.

1 Like
4

@vague Thank you! I wracked my head trying to remember a crate that self-hosts its documentation but failed to find any.

I noticed it deletes the docs/.lock file before uploading the artifact. Do you know what that file does?

@jofas Yeah, but the curious thing is that when setting a custom target directory, it creates debug and release folders beside the doc folder.

.
├── Cargo.toml
├── docs // This is generated as the result of `cargo doc --target-dir docs`.
│   ├── debug
│   ├── doc
├── src
├── target
│   ├── debug
│   └── doc
└── tests
5

The debug and release directories are where dependencies of the to be documented crates are placed. These dependencies are necessary for compiling the to be documented crate when documenting them, but are no longer necessary once everything is documented.

2 Likes
6

Looks like a file lock to me that is used to synchronize access to the output directory between multiple rustdoc processes.

1 Like
7

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.