rust-lang / rust-lang/docs.rs

support crate authors in checking if docs work in their CI setup.

Open
#3,202 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
1.2k
Forks
232
Avg merge
11h 35m
Merged PRs (30d)
60

Description

I'm not sure about the best approach here. this is currently more or less a braindump of my current thoughts
about this.

The use-case is: crates wanting to validate their docs-build in their CI.

Currently we're recommending cargo docs-rs, which duplicates our custom metadata reading, generates a custom cargo command to check if the docs-build works.

current caveats:

  • the command is not exactly the same, since the logic is duplicated, it might diverge more
  • it's not using the docker build-image, so crates that need c-libraries need to install them themselves in the github workflow, and might diverge from our build-image.
  • when your build script does network access, it will pass, while docs.rs fails.
  • when your build script writes to the wrong folder, it will pass, while dosc.rs fails.
1) just reduce duplication

create & release a subcrate that just contains the cargo-command-creation and uses our metadata library. cargo-docs-rs can use it

2) do our own cargo docs-rs

build & release our own binary as subcrate, use whatever is needed from the codebase.

3) perfect world

build something that

  1. uses rustwide & docker
  2. uses
  3. and uses the correct command.

best case it's in a way that docs.rs itself is using the same component, and the new cargo docs-rs command would just use the same component.

Now, thinking about this: how far away is this from just running docs_rs_builder build crate ./local_path?

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by comparing the recommended cargo-docs-rs command with docs_rs_builder build crate ./local_path, then read how rustwide and the Docker build-image are used. Define which approach should be selected and verify that CI checks use the same command, metadata handling, and build restrictions as docs.rs.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, rust
Domain
build-system, ci-cd, devops
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.