mat

0 Followers · 0 Following

• Joined on 2025-11-02

Repositories

1

Projects Packages Public Activity Starred Repositories

rust-crate-docgen (0.1.50)

Published 2026-04-26 22:50:24 +02:00 by mat

Installation

Set up this registry in the Cargo configuration file (for example ~/.cargo/config.toml):

[registry]
default = "gitea"

[registries.gitea]
index = "sparse+" # Sparse index
# index = "" # Git

[net]
git-fetch-with-cli = true

To install the package using Cargo, run the following command:

cargo add rust-crate-docgen@0.1.50

For more information on the Cargo registry, see the documentation.

About this package

rust-crate-docgen

Structure-first Rust crate documentation automation for CLI and library users.

Purpose

rust-crate-docgen is intended to automate documentation generation, validation, and publication-readiness for Rust crates by discovering facts from repository structure instead of relying on hand-maintained adapters.

Target outcome:

1. generated docs stay aligned with current code
2. published crate docs on docs.rs stay discoverable
3. examples and snippets are validated, not trusted
4. the tool can document itself using the same structure it expects from other crates

Why this project exists

Current crates in this repository already show the same recurring problems:

• public capability exists in code, but is hard to discover in published docs
• generated API references exist, but they are raw and hard to use as onboarding docs
• runnable examples drift from current structure or only demonstrate inline usage
• design docs and current supported contract get mixed together
• LLM-authored prose can drift unless machine-validated against code and examples

This project is meant to solve those problems once in a reusable way for:

• agent-flow
• plan-kit
• later agent-cli
• other Rust crates following the same structure

Primary design decision

Version 1 is structure-first:

• no project-specific adapters
• no hand-maintained semantic mapping layer
• repository convention is the contract
• tool discovers everything it can from folder structure, code, examples, tests, and generated artifacts

If a future problem cannot be solved through structure, it may justify a narrow configuration layer later. That is not part of the initial design.

Current product surface

Current code exposes same product flow through library facade and CLI:

• scan crate structure and derive current facts
• generate committed docs fragments, Mermaid architecture graph, and docs.rs include content
• verify freshness, published support claims, snippets, and runnable examples
• emit machine-readable quality summaries for release automation

Generated docs under docgen/generated/ are committed publish inputs for this crate. Normal crate changes should regenerate those files before commit, then commit source plus generated docs together:

cargo run --quiet --manifest-path rust-crate-docgen/Cargo.toml -- generate rust-crate-docgen

bash rust-crate-docgen/run-unit-tests.sh and source-publish workflow both fail when committed generated artifacts are stale. Publish uses committed tree and checks packaged source crate still contains every committed generated file.

Install CLI

rust-crate-docgen keeps one version for source crate publish and CLI bundle distribution. Same publish workflow run that pushes crate to Gitea registry also uploads linux x86_64 CLI bundle artifact from same commit.

• install from source crate registry when local Rust toolchain is fine:

cargo install --locked --registry gitea rust-crate-docgen --version <version>

• download prebuilt workflow artifact rust-crate-docgen-cli-linux-x86_64-v<version> when consumer wants standalone executable. Uploaded bundle contains:
  • rust-crate-docgen-v<version>-linux-x86_64.tar.gz
  • rust-crate-docgen-v<version>-linux-x86_64.tar.gz.sha256
  • binary-release-manifest.json

tar -xzf rust-crate-docgen-v<version>-linux-x86_64.tar.gz
./rust-crate-docgen-v<version>-linux-x86_64/rust-crate-docgen scan <crate-root>

Two usage modes

The final project should support two equally important ways of use.

1. CLI tool use

Run against a crate root and perform tasks such as:

• extract facts
• generate docs
• generate example assets
• verify freshness with explicit verify-freshness command
• validate snippets
• smoke-test examples

Supported command shape:

rust-crate-docgen scan <crate-root>
rust-crate-docgen generate <crate-root>
rust-crate-docgen verify <crate-root>
rust-crate-docgen quality-report <crate-root>
rust-crate-docgen verify-freshness <crate-root>

verify-freshness replaces ambiguous verify freshness so rust-crate-docgen verify freshness now honors documented verify [crate-root] contract for crate roots literally named freshness.

2. Programmatic dependency use

Other tools and pipelines should be able to depend on the library and call it directly.

Expected consumers:

• release automation
• doc pipelines in other Rust tools
• larger orchestration tools that want doc generation/verification as one stage

Supported library entrypoint:

Library consumers should start with rust_crate_docgen::api. Crate root no longer mirrors low-level helper exports.

Current library API shape:

use rust_crate_docgen::api::{generate, scan, verify, ScanRequest};

let scan_report = scan(&ScanRequest::new(crate_root))?;
let generated = generate(&scan_report.generate_request())?;
let verified = verify(&scan_report.verify_request())?;
assert!(generated.docs_fragments.fragment_count > 0);
assert!(verified.is_success());

Advanced prose customization stays under same facade:

use rust_crate_docgen::api::{
    generate_with_prose_writer, scan, ConstrainedProseOutput, ConstrainedProseSection,
    ConstrainedProseWriter, ScanRequest,
};

struct EchoWriter;

impl ConstrainedProseWriter for EchoWriter {
    fn write(
        &self,
        prompt: &rust_crate_docgen::api::ConstrainedProsePrompt,
    ) -> Result<ConstrainedProseOutput, String> {
        Ok(ConstrainedProseOutput {
            kind: prompt.template.kind,
            sections: prompt
                .template
                .sections
                .iter()
                .map(|section| ConstrainedProseSection {
                    heading: section.heading.clone(),
                    statements: section.allowed_statements.clone(),
                })
                .collect(),
        })
    }
}

let scan_report = scan(&ScanRequest::new(crate_root))?;
let generated = generate_with_prose_writer(&scan_report.generate_request(), &EchoWriter)?;
assert!(generated.docs_fragments.fragment_count > 0);
# Ok::<(), Box<dyn std::error::Error>>(())

Machine-readable quality summary:

use rust_crate_docgen::api::{quality_report, scan, ScanRequest};

let scan_report = scan(&ScanRequest::new(crate_root))?;
let quality = quality_report(&scan_report.verify_request())?;
assert!(matches!(quality.status, rust_crate_docgen::api::QualityStatus::Pass));
# Ok::<(), Box<dyn std::error::Error>>(())

Self-hosting goal

The project should be able to generate and validate documentation for itself.

That means repository structure defined here is not only internal plan; it is first real example future tool should be able to consume.

Repository structure

Current canonical layout:

rust-crate-docgen/
  Cargo.toml
  Cargo.lock
  README.md
  src/
  examples/
  tests/
    fixtures/
  docs/
    contract/
    design/
  docgen/
    generated/
    scenarios/
    spec/

Important documents and machine inputs

• docs/design/findings.md — motivation gathered from repo review
• docs/design/architecture.md — top-to-bottom design for library and CLI
• docs/design/roadmap.md — implementation phases
• docs/contract/published-surfaces.md — docs.rs contract
• architecture-test.toml — architecture policy reused for tests and generated Mermaid graph
• docs/contract/repository-structure.md — canonical repository layout contract
• docgen/spec/repository-contract.json — machine-readable repository contract
• docgen/spec/fixture-matrix.json — machine-readable fixture inventory

Current state

This crate now ships library facade plus CLI facade over same engine.

Dependencies

ID	Version
rust-arch-test-kit	^0.4
serde	^1
serde_json	^1
syn	^2
thiserror	^2
toml	^0.8

Details

Cargo

2026-04-26 22:50:24 +02:00

2

84 KiB

Assets (1)

rust-crate-docgen-0.1.50.crate 84 KiB

Versions (5) View all

0.1.51 2026-04-27

0.1.50 2026-04-26

0.1.47 2026-04-26

0.1.44 2026-04-26

0.1.43 2026-04-26