Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add pre-reqs and tasks for launching a live version of the docs site #1808

Merged
merged 3 commits into from
Sep 23, 2024

Conversation

analogrelay
Copy link
Member

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)

  1. Added the nightly toolchain to the devcontainer. We don't use this for our primary build, but docs.rs does use it and we use some features from it (primarily things like doc_auto_cfg to show "requires x feature" messages). Also, rustdoc has a nightly-only feature to generate a root index.html for all the crates in the repo. Not a huge need, but useful.
  2. Installed cargo-watch and http-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.
  3. Add a VSCode Task (this is usable on any machine, if you have the pre-reqs, it's not tied to Codespaces/Devcontainers) to "launch" the docs site. This uses cargo-watch to automatically rebuild the docs on every change, and then launches a static server on port 8080 to serve the docs. The http-server is particularly necessary for Codespaces/Devcontainers where you can't just open the index.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.

@analogrelay
Copy link
Member Author

(I looked in to using cargo-docs-rs to fully emulate the docs.rs build, but it doesn't have a convenient "build for all packages" mode like cargo doc --workspace)

Copy link
Member

@heaths heaths left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with this, but I leave it up to @weshaggard and @hallipr if we want to do something like this. We haven't really focused much on our devcontainers, but if people are using them, great! That said, taking more dependencies on third-party tools is risky, especially since component governance will soon be enforced and we'll likely end up needing to review all dependencies (and likely transitive dependencies).

@weshaggard
Copy link
Member

I'm fine with this as it will only impact folks using devcontainers. However, as Heath mentions it will need to remain updated.

@analogrelay analogrelay merged commit b4ecd85 into feature/track2 Sep 23, 2024
43 checks passed
@analogrelay analogrelay deleted the ashleyst/docserver-task branch September 23, 2024 16:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants