Skip to content

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

@syphar

Description

@syphar

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?

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions