pydocstring 0.3.0

A zero-dependency Rust parser for Python docstrings (Google and NumPy styles) with a unified syntax tree and byte-precise source locations
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

//! Example: Auto-detecting docstring style with `parse()`
//!
//! Demonstrates the unified `parse()` entry point, which detects the style
//! automatically and returns a `Parsed` result. The root node kind is always
//! the style-neutral `DOCUMENT`; `Parsed::style()` reports the detected style:
//!
//! - `Style::Google` — Google style (section headers ending with `:`)
//! - `Style::NumPy`  — NumPy style (section headers with `---` underlines)
//! - `Style::Plain`  — no recognised section markers (summary/extended
//!   summary only, or unrecognised styles such as Sphinx)

use pydocstring::parse::Style;
use pydocstring::parse::parse;

fn show(label: &str, input: &str) {
    let parsed = parse(input);
    let style_label = match parsed.style() {
        Style::Google => "Google",
        Style::NumPy => "NumPy",
        Style::Plain => "Plain",
        // `Style` is #[non_exhaustive]: future styles land here.
        _ => "Unknown",
    };

    println!(
        "── {} → {} ──────────────────────────────────────────",
        label, style_label
    );
    print!("{}", parsed.pretty_print());
    println!();
}

fn main() {
    println!("╔══════════════════════════════════════════════════╗");
    println!("║        Auto-detecting Docstring Style            ║");
    println!("╚══════════════════════════════════════════════════╝");
    println!();

    show(
        "Google",
        r#"
Calculate the area of a rectangle.

Args:
    width (float): The width of the rectangle.
    height (float): The height of the rectangle.

Returns:
    float: The area of the rectangle.
"#,
    );

    show(
        "NumPy",
        r#"
Calculate the area of a rectangle.

Parameters
----------
width : float
    The width of the rectangle.
height : float
    The height of the rectangle.

Returns
-------
float
    The area of the rectangle.
"#,
    );

    show("Plain (summary only)", "Calculate the area of a rectangle.");

    show(
        "Plain (summary + extended)",
        r#"
Calculate the area of a rectangle.

Takes width and height as arguments and returns their product.
Negative values will raise a ValueError.
"#,
    );
}