cargo_doc_docusaurus/
lib.rs

1//! Convert rustdoc JSON output to Docusaurus-compatible markdown documentation.
2//!
3//! This library provides functionality to parse rustdoc's JSON output and convert it
4//! to well-formatted markdown files with React component integration for Docusaurus sites.
5//!
6//! # Example
7//!
8//! ```no_run
9//! use cargo_doc_docusaurus::{convert_json_file, ConversionOptions};
10//! use std::path::Path;
11//!
12//! let options = ConversionOptions {
13//!     input_path: Path::new("target/doc/my_crate.json"),
14//!     output_dir: Path::new("docs"),
15//!     include_private: false,
16//!     base_path: "",
17//!     workspace_crates: &[],
18//!     sidebarconfig_collapsed: false,
19//!     sidebar_output: None,
20//!     sidebar_root_link: None,
21//! };
22//!
23//! convert_json_file(&options).expect("Conversion failed");
24//! ```
25
26pub mod converter;
27pub mod parser;
28pub mod writer;
29
30pub use rustdoc_types;
31
32use anyhow::Result;
33use std::path::Path;
34
35/// Options for converting rustdoc JSON to markdown.
36pub struct ConversionOptions<'a> {
37  /// Path to the input rustdoc JSON file
38  pub input_path: &'a Path,
39  /// Directory where markdown files will be written
40  pub output_dir: &'a Path,
41  /// Whether to include private items in the output
42  pub include_private: bool,
43  /// Base path for links (e.g., "/docs/runtime/rust" for Docusaurus routing)
44  pub base_path: &'a str,
45  /// List of workspace crate names - external crates in this list will use internal links
46  pub workspace_crates: &'a [String],
47  /// Whether to generate sidebar categories as collapsed
48  pub sidebarconfig_collapsed: bool,
49  /// Custom path for the sidebar configuration file
50  pub sidebar_output: Option<&'a Path>,
51  /// URL for the 'Go back' link in root crate sidebars
52  pub sidebar_root_link: Option<&'a str>,
53}
54
55/// Convert a rustdoc JSON file to markdown (multi-file output).
56///
57/// This is the main entry point for library usage. Generates one file per module.
58///
59/// # Arguments
60///
61/// * `options` - Configuration for the conversion
62///
63/// # Returns
64///
65/// Returns `Ok(())` on success, or an error if the conversion fails.
66///
67/// # Example
68///
69/// ```no_run
70/// use cargo_doc_docusaurus::{convert_json_file, ConversionOptions};
71/// use std::path::Path;
72///
73/// let options = ConversionOptions {
74///     input_path: Path::new("target/doc/my_crate.json"),
75///     output_dir: Path::new("docs"),
76///     include_private: false,
77///     base_path: "",  // Optional: use "/docs/runtime/rust" for Docusaurus routing
78///     workspace_crates: &[],
79///     sidebarconfig_collapsed: false,
80///     sidebar_output: None,
81///     sidebar_root_link: None,
82/// };
83///
84/// convert_json_file(&options).expect("Conversion failed");
85/// ```
86pub fn convert_json_file(options: &ConversionOptions) -> Result<()> {
87  let crate_data = parser::load_rustdoc_json(options.input_path)?;
88  let output = converter::convert_to_markdown_multifile(
89    &crate_data,
90    options.include_private,
91    options.base_path,
92    options.workspace_crates,
93    options.sidebarconfig_collapsed,
94    options.sidebar_root_link,
95  )?;
96
97  // Write to crate-specific subdirectory
98  let crate_output_dir = options.output_dir.join(&output.crate_name);
99  writer::write_markdown_multifile_with_sidebar_path(
100    &crate_output_dir,
101    &output,
102    options.sidebar_output,
103  )?;
104  Ok(())
105}
106
107/// Convert rustdoc JSON data (already loaded) to markdown.
108///
109/// Use this if you want more control over the loading and writing process.
110///
111/// # Arguments
112///
113/// * `json_data` - The rustdoc JSON as a string
114/// * `include_private` - Whether to include private items
115///
116/// # Returns
117///
118/// Returns the markdown as a String, or an error.
119pub fn convert_json_string(json_data: &str, include_private: bool) -> Result<String> {
120  let crate_data: rustdoc_types::Crate = serde_json::from_str(json_data)?;
121  converter::convert_to_markdown(&crate_data, include_private)
122}
cargo_doc_docusaurus/lib.rs

cargo_doc_docusaurus/
lib.rs
