cargo-orthohelp 0.8.0

OrthoConfig documentation tooling for IR generation.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89

//! About topic rendering for `PowerShell` help output.

use crate::ir::{
    LocalizedConfigDiscoveryMeta, LocalizedDocMetadata, LocalizedPathPattern,
    LocalizedPrecedenceMeta,
};
use crate::powershell::text::push_line;
use crate::schema::SourceKind;

/// Renders the about topic content for a module.
#[must_use]
pub fn render_about(metadata: &LocalizedDocMetadata, module_name: &str) -> String {
    let mut output = String::new();

    push_line(&mut output, "TOPIC");
    push_line(&mut output, &format!("    about_{module_name}"));
    push_line(&mut output, "");

    push_line(&mut output, "SHORT DESCRIPTION");
    push_line(&mut output, &format!("    {}", metadata.about));
    push_line(&mut output, "");

    push_line(&mut output, "LONG DESCRIPTION");
    push_line(&mut output, &format!("    {}", metadata.about));

    render_synopsis(&mut output, metadata);
    render_discovery(&mut output, metadata.sections.discovery.as_ref());
    render_precedence(&mut output, metadata.sections.precedence.as_ref());

    output
}

fn render_synopsis(output: &mut String, metadata: &LocalizedDocMetadata) {
    let Some(synopsis) = metadata.synopsis.as_ref() else {
        return;
    };
    push_line(output, "");
    push_line(output, "    Synopsis:");
    push_line(output, &format!("      {synopsis}"));
}

fn render_discovery(output: &mut String, discovery: Option<&LocalizedConfigDiscoveryMeta>) {
    let Some(discovery_meta) = discovery else {
        return;
    };
    push_line(output, "");
    push_line(output, "    Configuration discovery:");
    if discovery_meta.search_paths.is_empty() {
        push_line(output, "      (not specified)");
        return;
    }
    for path in &discovery_meta.search_paths {
        push_line(output, &format_discovery_path(path));
    }
}

fn render_precedence(output: &mut String, precedence: Option<&LocalizedPrecedenceMeta>) {
    let Some(precedence_meta) = precedence else {
        return;
    };
    push_line(output, "");
    push_line(output, "    Precedence:");
    for source in &precedence_meta.order {
        push_line(output, &format!("      - {}", source_label(source)));
    }
    if let Some(rationale) = precedence_meta.rationale.as_ref() {
        push_line(output, "");
        push_line(output, &format!("    {rationale}"));
    }
}

fn format_discovery_path(path: &LocalizedPathPattern) -> String {
    path.note
        .as_deref()
        .filter(|note| !note.is_empty())
        .map_or_else(
            || format!("      - {}", path.pattern),
            |note| format!("      - {} ({})", path.pattern, note),
        )
}

const fn source_label(source: &SourceKind) -> &'static str {
    match source {
        SourceKind::Defaults => "Defaults",
        SourceKind::File => "File",
        SourceKind::Env => "Environment",
        SourceKind::Cli => "CLI",
    }
}