diplodocus 0.15.0

Build coherent documentation websites for polyglot software projects.
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
//! Typed static API semantics. Signatures, documents, and evidence remain shared.

use serde::{Deserialize, Serialize};

use super::{ItemReference, SignatureExpression, SourceEvidence};

/// Language-specific facts for one canonical item.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(
    tag = "language",
    content = "data",
    rename_all = "kebab-case",
    deny_unknown_fields
)]
pub enum ItemLanguageData {
    /// C++ declarations selected by Doxygen.
    Cpp(super::CppItemData),
    /// Compiler-resolved Rust declarations and implementation relationships.
    Rust(RustItemData),
    /// Julia declaration semantics from maintained source.
    Julia(JuliaItemData),
    /// Python declaration semantics after source/stub reconciliation.
    Python(PythonItemData),
    /// R declaration semantics after namespace/source/Rd reconciliation.
    R(RItemData),
}

/// An additional lookup name for its owning canonical item, never another item.
///
/// A Python type alias is a distinct declaration represented by
/// [`PythonDeclaration::TypeAlias`], not by this record. Rd aliases must be
/// apportioned to their actual generic or method, even when they share a page.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ItemAlias {
    /// Package-scoped lookup spelling, including Python module qualification.
    pub qualified_name: String,
    /// Semantics of the declaration that introduced the name.
    pub kind: ItemAliasKind,
    /// Re-export, assignment, or Rd evidence in source order.
    pub sources: Vec<SourceEvidence>,
}

/// Why an additional name refers to an existing item.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ItemAliasKind {
    /// A public Rust reexport resolved by the compiler.
    RustReexport,
    /// A statically resolved Julia import or reexport.
    JuliaImport,
    /// A statically proven assignment of the same Julia binding.
    JuliaAssignment,
    /// A statically resolved import or re-export.
    PythonReexport,
    /// A statically proven assignment of the same object.
    PythonAssignment,
    /// A statically proven assignment of the same R function.
    RAssignment,
    /// An Rd lookup name reconciled with a maintained declaration.
    RdAlias,
}

/// Rust facts independent of an item's signature and documentation.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RustItemData {
    /// Declaration category reported by rustdoc.
    pub declaration: RustDeclarationKind,
    /// Preferred publicly reachable path, including the crate name.
    pub public_path: String,
    /// Enclosing type, trait, or variant for an embedded member.
    pub owner: Option<ItemReference>,
    /// Implementation identity for an implementation member.
    pub implementation: Option<String>,
    /// Implementations associated with this type or trait.
    pub implementations: Vec<RustImplementation>,
    /// Declaration attributes retained by rustdoc.
    pub attributes: Vec<String>,
}

/// Rust declaration categories that refine the shared item classification.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum RustDeclarationKind {
    /// Crate or module.
    Module,
    /// Struct declaration.
    Struct,
    /// Enum declaration.
    Enum,
    /// Union declaration.
    Union,
    /// Trait declaration.
    Trait,
    /// Enum variant.
    Variant,
    /// Free function.
    Function,
    /// Inherent or trait method.
    Method,
    /// Struct or variant field.
    Field,
    /// Named or associated constant.
    Constant,
    /// Static variable.
    Static,
    /// Named type alias.
    TypeAlias,
    /// Trait or implementation associated type.
    AssociatedType,
    /// Declarative or procedural macro.
    Macro,
    /// An implementation block with its own documentation.
    Implementation,
}

/// One compiler-resolved implementation, embedded in its owning type's page.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RustImplementation {
    /// Stable semantic context, independent of compiler IDs and source order.
    pub identity: String,
    /// Structured Rust implementation header.
    pub signature: SignatureExpression,
    /// Addressable documentation attached directly to the implementation block.
    pub documentation_item: Option<ItemReference>,
    /// Original implementation location when native attribution is available.
    pub source_location: Option<super::SourceLocation>,
    /// Implemented trait path, when this is a trait implementation.
    pub trait_name: Option<String>,
    /// Local trait identity when its definition belongs to this snapshot.
    pub trait_target: Option<ItemReference>,
    /// Implementation members in declaration order.
    pub members: Vec<ItemReference>,
    /// Whether the compiler synthesized this implementation.
    pub is_synthetic: bool,
    /// Whether the implementation applies through a blanket bound.
    pub is_blanket: bool,
}

/// Python facts independent of an item's structured signature and prose.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PythonItemData {
    /// Visibility established by the static export policy.
    pub visibility: PythonVisibility,
    /// Supported declaration semantics.
    pub declaration: PythonDeclaration,
    /// Decorators in source order, retained without evaluation.
    pub decorators: Vec<PythonDecorator>,
}

/// Visibility is unknown when dynamic exports prevent a static decision.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PythonVisibility {
    /// Statically public API.
    Public,
    /// Retained private implementation detail.
    Private,
    /// Retained declaration whose public visibility is not established.
    Unknown,
}

/// The supported Python declaration shapes.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum PythonDeclaration {
    /// One module, possibly reconciled from both source and a stub.
    Module {
        /// Which maintained declarations contribute to this module.
        source: PythonModuleSource,
        /// Export authority, including an explicitly unknown dynamic surface.
        exports: PythonExports,
    },
    /// A function, method, constructor, or individually addressable overload.
    Callable {
        /// Binding and constructor behavior.
        binding: PythonCallableKind,
        /// Whether the declaration uses `async def`.
        is_async: bool,
        /// Family membership, separate from lexical child containment.
        role: PythonCallableRole,
    },
    /// A class with supported explicit or generated constructor semantics.
    Class {
        /// Base expressions in declaration order, never evaluated.
        bases: Vec<SignatureExpression>,
        /// Constructor facts that can be established statically.
        constructor: PythonConstructor,
    },
    /// A property whose getter signature remains on the owning item.
    Property {
        /// Whether a supported setter declaration is present.
        has_setter: bool,
        /// Whether a supported deleter declaration is present.
        has_deleter: bool,
    },
    /// An annotated or literal constant; syntax remains in `Item::signatures`.
    Constant,
    /// An instance or class field; syntax remains in `Item::signatures`.
    Field,
    /// A distinct named type alias, rather than another name for one item.
    TypeAlias {
        /// Unevaluated aliased type expression.
        target: SignatureExpression,
    },
}

/// Origin of the reconciled module surface.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PythonModuleSource {
    /// A loaded module without contributing maintained source/stub observations.
    Runtime,
    /// Maintained `.py` declarations.
    Implementation,
    /// Maintained `.pyi` declarations with no implementation required.
    StubOnly,
    /// Maintained `.py` and `.pyi` declarations reconciled field by field.
    ImplementationAndStub,
}

/// Static export authority; names are retained in declaration order.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum PythonExports {
    /// The actual export names observed after importing the selected checkout.
    Runtime {
        /// Runtime __all__, including the result of computed export expressions.
        names: Vec<String>,
    },
    /// Public definitions and explicitly public imports determine the surface.
    Implicit,
    /// A supported literal `__all__` is authoritative, including an empty list.
    Explicit {
        /// Exported local names in declaration order.
        names: Vec<String>,
        /// Evidence for the declaration, separately from definitions.
        sources: Vec<SourceEvidence>,
    },
    /// A computed export expression must be accompanied by a diagnostic.
    Dynamic {
        /// Unevaluated expression, never guessed into an export list.
        expression: SignatureExpression,
        /// Evidence for the unsupported export declaration.
        sources: Vec<SourceEvidence>,
    },
}

/// Python callable binding semantics.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PythonCallableKind {
    /// Module-level function.
    Function,
    /// Method bound to an instance.
    InstanceMethod,
    /// Method with no implicit receiver.
    StaticMethod,
    /// Method bound to a class.
    ClassMethod,
    /// Explicit `__init__` or `__new__` declaration.
    Constructor,
}

/// Every callable has one family item; overloads are separate member items.
///
/// A family with no overloads is an ordinary callable. Its signatures and
/// documentation remain on `Item`. An overloaded family holds the reconciled
/// public signatures; each overload also holds its own signature and evidence.
/// Stub and implementation declarations do not create extra family items.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum PythonCallableRole {
    /// Canonical public entry point and concept target.
    Family {
        /// Addressable overloads in declaration order.
        overloads: Vec<ItemReference>,
    },
    /// An individual overload declaration.
    Overload {
        /// Canonical callable family.
        family: ItemReference,
    },
}

/// Constructor semantics supported without executing class decorators.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum PythonConstructor {
    /// No constructor semantics have been established by the extractor.
    Unspecified,
    /// A maintained constructor declaration.
    Explicit {
        /// Constructor callable family.
        item: ItemReference,
    },
    /// Supported dataclass options, after applying known decorator defaults.
    Dataclass {
        /// Fields in declaration order.
        fields: Vec<ItemReference>,
        /// Whether runtime discovery already incorporated inherited fields.
        #[serde(default, skip_serializing_if = "std::ops::Not::not")]
        fields_include_inherited: bool,
        /// Whether the decorator generates `__init__`.
        init: bool,
        /// Whether the class is frozen.
        frozen: bool,
    },
}

/// Decorator syntax and any statically established meaning.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PythonDecorator {
    /// Structured unevaluated syntax, including call arguments.
    pub expression: SignatureExpression,
    /// Meaning established by the supported static subset.
    pub semantics: PythonDecoratorSemantics,
    /// Exact decorator evidence when available.
    pub sources: Vec<SourceEvidence>,
}

/// Recognizing a decorator never authorizes evaluating it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum PythonDecoratorSemantics {
    /// `typing.overload`.
    Overload,
    /// A property getter.
    Property,
    /// A property setter.
    PropertySetter,
    /// A property deleter.
    PropertyDeleter,
    /// `staticmethod`.
    StaticMethod,
    /// `classmethod`.
    ClassMethod,
    /// Supported `dataclasses.dataclass` options.
    Dataclass,
    /// `contextlib.contextmanager` on a generator callable.
    ContextManager,
    /// Syntax retained without claiming its runtime semantics.
    Unknown,
}

/// R facts independent of shared formals, documentation, and source evidence.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RItemData {
    /// Whether `NAMESPACE` explicitly exports the declaration by name.
    /// A registered S3 method can be public through dispatch without this flag.
    pub exported: bool,
    /// An Rd topic marked `\\keyword{internal}`, retained but omitted from discovery.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub internal: bool,
    /// Shared Rd topic coordinates, independent of declaration identity.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub help_topic: Option<RHelpTopic>,
    /// Supported maintained-source and namespace semantics.
    pub declaration: RDeclaration,
}

/// A help topic shared by several maintained R declarations.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RHelpTopic {
    /// Static Rd topic name.
    pub name: String,
    /// Declaration that owns aliases naming the topic as a whole.
    pub primary: ItemReference,
    /// All documented declarations in canonical identity order.
    pub members: Vec<ItemReference>,
}

/// Static R declarations supported by the MVP corpus.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum RDeclaration {
    /// A maintained binding with a statically known literal value.
    Constant,
    /// A standalone help topic for deprecated aliases.
    DeprecatedTopic,
    /// A dataset documented by an Rd topic with `\docType{data}`.
    Dataset,
    /// An ordinary named function.
    Function,
    /// An S3 generic is itself the canonical callable family.
    S3Generic {
        /// Name passed to `UseMethod`, which need not equal the binding name.
        dispatch_name: String,
        /// Explicit second `UseMethod` argument when supplied.
        dispatch_object: Option<SignatureExpression>,
        /// Registered method identities in deterministic declaration order.
        methods: Vec<ItemReference>,
    },
    /// One addressable S3 method, independent of its Rd topic and alias names.
    S3Method {
        /// Resolved local or externally imported generic.
        generic: RGenericReference,
        /// Dispatch class, including the special `default` class.
        class: String,
        /// Namespace registration evidence, separate from the definition.
        registration: Vec<SourceEvidence>,
    },
    /// A function that statically constructs instances of known S3 classes.
    Constructor {
        /// Class vector in declared dispatch order.
        classes: Vec<String>,
    },
}

/// Generic identity without inventing an item for an unsupplied R package.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum RGenericReference {
    /// Generic represented in this workspace, possibly in another package.
    Workspace {
        /// Canonical generic identity.
        item: ItemReference,
    },
    /// Generic imported from an R package outside the supplied workspace.
    External {
        /// R package name, such as `stats`.
        package: String,
        /// Generic name, such as `predict`.
        name: String,
    },
}

/// Julia facts independent of signature syntax and documentation.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct JuliaItemData {
    /// Lexical module containing the maintained declaration.
    pub defining_module: String,
    /// Explicit API visibility, separate from documentation-based inclusion.
    pub visibility: JuliaVisibility,
    /// Supported declaration semantics.
    pub declaration: JuliaDeclaration,
}

/// Julia distinguishes exported API from public qualified API.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum JuliaVisibility {
    /// An `export` declaration makes this binding public.
    Exported,
    /// A `public` declaration marks this binding without exporting it.
    Public,
    /// Neither declaration marks this binding as public.
    Private,
}

/// Static Julia declarations represented without evaluating package code.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum JuliaDeclaration {
    /// A lexical module, including `baremodule`.
    Module {
        /// Whether this module omits Julia's implicit Base imports.
        bare: bool,
    },
    /// A function family, authored method, or macro definition.
    Callable {
        /// Function, constructor, or macro semantics.
        binding: JuliaCallableKind,
        /// Family membership is independent of lexical containment.
        role: JuliaCallableRole,
        /// An external module owning a function extended by this package.
        external_owner: Option<String>,
    },
    /// A type is also the canonical family for its explicit constructors.
    Type {
        /// Struct, abstract, or primitive type semantics.
        flavor: JuliaTypeKind,
        /// Declared type parameters and bounds.
        parameters: Vec<SignatureExpression>,
        /// Unevaluated supertype when supplied.
        supertype: Option<SignatureExpression>,
        /// Maintained constructor methods, without synthesized defaults.
        constructors: Vec<ItemReference>,
    },
    /// A maintained constant binding.
    Constant,
    /// A struct field, including a `const` field.
    Field {
        /// Whether the source uses Julia's const field marker.
        is_const: bool,
    },
}

/// Julia callable declaration semantics.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum JuliaCallableKind {
    /// A generic function or its authored method.
    Function,
    /// An explicit inner or outer constructor.
    Constructor,
    /// A maintained macro definition, without expansion.
    Macro,
}

/// An addressable authored method belongs to one canonical family.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum JuliaCallableRole {
    /// A generic function, or a macro with its declaration signature.
    Family {
        /// Maintained method declarations in source order.
        methods: Vec<ItemReference>,
    },
    /// One authored method, rather than a synthesized runtime method.
    Method {
        /// Local family or type whose constructor this method implements.
        family: ItemReference,
        /// Normalized dispatch syntax used for identity and method references.
        dispatch: SignatureExpression,
    },
}

/// Supported Julia type flavors.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "kebab-case", deny_unknown_fields)]
pub enum JuliaTypeKind {
    /// A concrete type with maintained fields.
    Struct {
        /// Whether the type uses `mutable struct`.
        mutable: bool,
    },
    /// An abstract type.
    Abstract,
    /// A primitive type with an unevaluated bit width.
    Primitive {
        /// Declared bit-width spelling.
        bits: Option<String>,
    },
}