plissken_core/
lib.rs

1//! plissken-core: Documentation extraction for Rust-Python hybrid projects
2//!
3//! This crate provides the core functionality for parsing Rust and Python
4//! source code and extracting documentation into a unified model.
5//!
6//! # API Structure
7//!
8//! The public API is organized into tiers:
9//!
10//! - **Core API** (root): Essential types for typical usage
11//! - **Detail API** ([`detail`]): Advanced types for fine-grained control
12//! - **Modules** (`config`, `parser`, `render`, etc.): Full module access
13//!
14//! # Quick Start
15//!
16//! ```ignore
17//! use plissken_core::{Config, RustParser, PythonParser, DocModel};
18//!
19//! // Load configuration
20//! let config = Config::from_file("plissken.toml")?;
21//!
22//! // Parse source files
23//! let mut rust_parser = RustParser::new();
24//! let rust_module = rust_parser.parse_file("src/lib.rs")?;
25//!
26//! // Build documentation model
27//! let model = DocModel::test("my-project")
28//!     .with_rust_module(rust_module);
29//! ```
30
31// =============================================================================
32// Module declarations
33// =============================================================================
34
35pub mod config;
36
37// Test utilities - only compiled for tests
38pub mod crossref;
39pub mod discover;
40pub mod docstring;
41pub mod error;
42pub mod manifest;
43pub mod model;
44pub mod parser;
45pub mod render;
46#[cfg(test)]
47pub mod test_fixtures;
48
49// =============================================================================
50// Core API - Essential types for typical usage (~20 types)
51// =============================================================================
52
53// Configuration
54pub use config::{Config, ConfigError, ConfigWarning, ValidationResult};
55// Configuration constants
56pub use config::{
57    CARGO_MANIFEST, DEFAULT_CRATES, DEFAULT_DOCS_RS_URL, DEFAULT_OUTPUT_FORMAT,
58    DEFAULT_OUTPUT_PATH, DEFAULT_TEMPLATE, PLISSKEN_CONFIG, PYPROJECT_MANIFEST, TEMPLATE_MDBOOK,
59    TEMPLATE_MKDOCS_MATERIAL, VERSION_SOURCE_CARGO, VERSION_SOURCE_PYPROJECT,
60};
61
62// Errors
63pub use error::{PlisskenError, Result};
64
65// Documentation model - top level
66pub use model::{CrossRef, CrossRefKind, DocModel, ProjectMetadata, SourceType};
67
68// Module containers
69pub use model::{PythonModule, RustModule};
70
71// Parsers
72pub use parser::{
73    Module as ParsedModule, Parser, ParserLanguage, create_parser, parser_for_extension,
74};
75pub use parser::{PythonParser, RustParser};
76
77// Rendering
78pub use render::{ModuleRenderer, RenderedPage, Renderer};
79pub use render::{ThemeAdapter, get_theme_adapter};
80
81// =============================================================================
82// Detail API - Advanced types for users who need fine-grained control
83// =============================================================================
84
85/// Advanced types for users who need fine-grained control over documentation.
86///
87/// These types are stable but not commonly needed for basic usage. Import from
88/// here when you need to inspect or construct individual documentation items.
89///
90/// # Example
91///
92/// ```ignore
93/// use plissken_core::detail::{RustStruct, PythonFunction, Visibility};
94///
95/// // Inspect a struct's fields
96/// if let Some(struct_) = get_rust_struct(model) {
97///     for field in &struct_.fields {
98///         println!("{}: {}", field.name, field.ty);
99///     }
100/// }
101/// ```
102pub mod detail {
103    // Rust item types
104    pub use crate::model::{
105        RustConst, RustEnum, RustFunction, RustImpl, RustItem, RustStruct, RustTrait, RustTypeAlias,
106    };
107
108    // Rust sub-types
109    pub use crate::model::{
110        RustAssociatedType, RustField, RustFunctionSig, RustParam, RustVariant, Visibility,
111    };
112
113    // Python item types
114    pub use crate::model::{PythonClass, PythonFunction, PythonItem, PythonVariable};
115
116    // Python sub-types
117    pub use crate::model::{PythonFunctionSig, PythonParam};
118
119    // Source location types
120    pub use crate::model::{SourceLocation, SourceSpan};
121
122    // Cross-reference types
123    pub use crate::model::RustItemRef;
124
125    // Docstring types
126    pub use crate::model::{ParamDoc, ParsedDocstring, RaisesDoc, ReturnDoc};
127
128    // PyO3 metadata (useful for cross-reference inspection)
129    pub use crate::model::{PyClassMeta, PyFunctionMeta};
130
131    // Discovery
132    pub use crate::discover::{DiscoveredModule, discover_python_modules, merge_modules};
133
134    // Manifest parsing
135    pub use crate::manifest::{CargoManifest, InferredConfig, PyProjectManifest};
136
137    // Cross-reference building
138    pub use crate::crossref::{
139        build_cross_refs, synthesize_python_from_rust, synthesize_python_modules_from_rust,
140    };
141
142    // Docstring parsing
143    pub use crate::docstring::{parse_docstring, parse_rust_doc};
144
145    // Render utilities
146    pub use crate::render::{
147        CrossRefLink, Language, crossref_link, link_to_python, link_to_rust, render_docstring,
148        render_examples, render_params_table, render_python_exposure_details, render_raises_table,
149        render_returns, render_rust_impl_details,
150    };
151}
152
153// =============================================================================
154// Backwards compatibility re-exports (deprecated, use detail:: instead)
155// =============================================================================
156
157// These are provided for backwards compatibility but should migrate to detail::
158// TODO: Add #[deprecated] once stabilized migration period ends
159
160// Commonly used detail types that were previously in root
161pub use model::{
162    ParsedDocstring, PythonClass, PythonFunction, PythonItem, PythonParam, PythonVariable,
163    RustEnum, RustField, RustFunction, RustImpl, RustItem, RustItemRef, RustParam, RustStruct,
164    RustTrait, SourceLocation, SourceSpan, Visibility,
165};
166
167// Discovery and manifest (commonly used)
168pub use discover::{DiscoveredModule, discover_python_modules, merge_modules};
169pub use manifest::{CargoManifest, InferredConfig, PyProjectManifest};
170
171// Cross-reference utilities
172pub use crossref::{
173    build_cross_refs, synthesize_python_from_rust, synthesize_python_modules_from_rust,
174};
175
176// Docstring utilities
177pub use docstring::{parse_docstring, parse_rust_doc};
178
179// Render utilities
180pub use render::{CrossRefLink, Language, crossref_link, link_to_python, link_to_rust};
181pub use render::{
182    render_docstring, render_examples, render_params_table, render_python_exposure_details,
183    render_raises_table, render_returns, render_rust_impl_details,
184};
plissken_core/lib.rs

plissken_core/
lib.rs
