Add pre-reqs and tasks for launching a live version of the docs site #1808
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Another semi-random idea to make development smoother ;).
I've been trying to keep up with docs as I work, because I know how annoying a deep API doc debt can be. While working on docs, it's really useful to be able to quickly see your changes in a "live" version of the site. This PR adds a few things to make that easier for folks working in Codespaces/DevContainers (and even for folks working on local machines in VS Code)
doc_auto_cfg
to show "requiresx
feature" messages). Also,rustdoc
has a nightly-only feature to generate a rootindex.html
for all the crates in the repo. Not a huge need, but useful.cargo-watch
andhttp-server
in the devcontainer. The former is a standard "watch my Rust files and re-run these commands if they change" and the latter is a simple rust-based static file HTTP server.cargo-watch
to automatically rebuild the docs on every change, and then launches a static server on port8080
to serve the docs. The http-server is particularly necessary for Codespaces/Devcontainers where you can't just open theindex.html
page up in a browser. A local user could just rebuild the site and open the page locally.I've been using this locally and it makes for a nice workflow, but I wanted to get the pre-reqs in place so I didn't have to keep reinstalling them whenever my codespace rebuilds (which is not too frequent but does happen). I also think it'd be useful for folks as they build out SDK APIs
Recording.2024-09-18.100117.mp4
All of this is fairly opt-in, except that Codespaces/Devcontainers will incur a slight increase in build time and image size from installing the nightly toolchain and tools. It's barely noticeable in my current experience.