Docs publish

[hakiers]

Task [744] (https://github.com/software-mansion/scarbs.xyz/issues/744)

This pull request adds support for publishing package documentation (docs) to registries that support it. It introduces the ability to generate, package, and upload documentation as part of the publish workflow, with the option to skip documentation publishing if desired. The changes include updates to the registry client interface, documentation packaging logic, and command-line arguments.

Documentation publishing support:

• Added a new no_docs flag to PublishArgs and corresponding logic to allow skipping documentation generation and upload during publish (scarb/src/bin/scarb/args.rs, scarb/src/bin/scarb/commands/publish.rs). [1] [2]
• Introduced a new docs field to PublishOpts and integrated logic to check if the registry supports documentation publishing and to generate/package docs if enabled (scarb/src/ops/publish.rs). [1] [2] [3]

Registry client interface and implementation:

• Extended the RegistryClient trait with supports_publish_docs and publish_docs methods, and implemented them for both HTTP and local registry clients (scarb/src/core/registry/client/mod.rs, scarb/src/core/registry/client/http.rs, scarb/src/core/registry/client/local.rs). [1] [2] [3]

Documentation packaging logic:

• Added a new docs module with logic to generate documentation via an external subcommand, tar and compress the output, and report statistics (scarb/src/ops/docs.rs, scarb/src/ops/mod.rs). [1] [2] [3]
• Added a helper to execute external subcommands and wait for completion (scarb/src/ops/subcommands.rs). [1] [2]

Registry index configuration:

• Updated the registry index configuration to support a docs-upload endpoint, including serialization/deserialization and tests (scarb/src/core/registry/index/config.rs). [1] [2] [3] [4]

( [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] )Part of #744

---

_{Stack created with GitHub Stacks CLI • Give Feedback 💬}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[hakiers]

It works 😀

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Suppressed comments (5)

scarb/src/ops/subcommands.rs:120

• cmd is used for three different meanings/types (&str input, resolved executable PathBuf, and Command), which makes the control flow harder to follow and increases the chance of mistakes. Rename to distinct identifiers (e.g., cmd_name, cmd_path, command) to make intent and types clear.

    cmd: &str,

scarb/src/ops/subcommands.rs:138

• cmd is used for three different meanings/types (&str input, resolved executable PathBuf, and Command), which makes the control flow harder to follow and increases the chance of mistakes. Rename to distinct identifiers (e.g., cmd_name, cmd_path, command) to make intent and types clear.

    let subcommand_dirs = SubcommandDirs::try_from(config)?;
    let Some(cmd) = find_external_subcommand(cmd, &subcommand_dirs)? else {
        bail!("no such command: `{cmd}`");
    };

    let mut cmd = Command::new(cmd);
    cmd.args(args);

scarb/src/core/registry/index/config.rs:17

• The JSON example in the doc comment is invalid because it’s missing a comma after the "index" entry. Add the trailing comma to keep the example copy-pastable and consistent with the test JSON below.

///   "dl": "https://example.com/api/v1/download/{package}/{version}",
///   "upload": "https://example.com/api/v1/packages/new",
///   "index": "https://example.com/index/{prefix}/{package}.json"
///   "docs-upload": "https://example.com/api/v1/docs/{package}/{version}"
/// }

scarb/src/core/registry/client/mod.rs:115

• Adding a new required method (publish_docs) to a public trait is a breaking change for any external RegistryClient implementers. To preserve backward compatibility, consider providing a default implementation that returns Ok(RegistryUpload::Failure(...unsupported...)) (similar to the local client), or otherwise ensure this change is coordinated with a semver-major bump / internal-only trait usage.

    async fn publish(&self, package: Package, tarball: LockedFile) -> Result<RegistryUpload>;

    /// State whether documentation can be published to this registry.
    async fn supports_publish_docs(&self) -> Result<bool> {
        Ok(false)
    }

    /// Publish documentation for a package to this registry.
    ///    
    /// This function can only be called if [`RegistryClient::supports_publish_docs`] returns `true`.
    async fn publish_docs(
        &self,
        package: PackageId,
        tarball: LockedFile,
        force: bool,
    ) -> Result<RegistryUpload>;

scarb/src/ops/docs.rs:35

• zstd compression level 22 is extremely CPU-intensive and may significantly increase publish latency (especially in CI or on lower-powered machines). Consider lowering the default level (or making it configurable) to balance upload size vs. runtime, since docs artifacts can be large and this runs during publish.

    const COMPRESSION_LEVEL: i32 = 22;
    let encoder = zstd::stream::Encoder::new(dst, COMPRESSION_LEVEL)?;