From d33f3ef35a6d1839414e438172f71a89fc6c5643 Mon Sep 17 00:00:00 2001 From: Lucas Tabis Date: Mon, 29 Apr 2024 21:10:04 +0200 Subject: [PATCH] chore!: Hide items that are not supposed to appear in the API (#16) * feat: replace generate_for_docusaurus and generate_for_mdbook functions by buider patterns to provide more options * feat: add slug option to docusaurus generation * chore: update docusaurus example with slug option * fix: slug path * chore: update docusaurus examples with generated slugs * fix: slug without options appens / to the module name * docs: update readme to reflect the changes * chore: fix lint * docs: update unresolved items * refact: hide function unused by the user --- src/doc_item.rs | 19 ++++++++++--------- src/glossary.rs | 2 +- src/lib.rs | 21 +++++++++++++++------ src/module/options.rs | 11 ----------- 4 files changed, 26 insertions(+), 27 deletions(-) diff --git a/src/doc_item.rs b/src/doc_item.rs index 3339f8d..780851e 100644 --- a/src/doc_item.rs +++ b/src/doc_item.rs @@ -7,6 +7,7 @@ use crate::{ }, ItemsOrder, }; +use serde::ser::SerializeStruct; /// Generic representation of documentation for a specific item. (a function, a custom type, etc.) #[derive(Debug, Clone)] @@ -23,8 +24,6 @@ pub enum DocItem { }, } -use serde::ser::SerializeStruct; - impl serde::Serialize for DocItem { fn serialize(&self, serializer: S) -> Result where @@ -124,7 +123,7 @@ impl Section { } impl DocItem { - pub fn new_function( + pub(crate) fn new_function( metadata: &[FunctionMetadata], name: &str, options: &Options, @@ -158,7 +157,7 @@ impl DocItem { } } - pub fn new_custom_type( + pub(crate) fn new_custom_type( metadata: CustomTypesMetadata, options: &Options, ) -> Result, AutodocsError> { @@ -173,12 +172,14 @@ impl DocItem { ) } + /// Get the index of the item, extracted from the `# rhai-autodocs:index` directive. pub fn index(&self) -> usize { match self { DocItem::CustomType { index, .. } | DocItem::Function { index, .. } => *index, } } + /// Get the name of the item. pub fn name(&self) -> &str { match self { DocItem::CustomType { metadata, .. } => metadata.display_name.as_str(), @@ -187,7 +188,7 @@ impl DocItem { } /// Find the order index of the item by searching for the index pattern. - pub fn find_index(doc_comments: &[String]) -> Result, AutodocsError> { + pub(crate) fn find_index(doc_comments: &[String]) -> Result, AutodocsError> { for line in doc_comments { if let Some((_, index)) = line.rsplit_once(RHAI_ITEM_INDEX_PATTERN) { return index @@ -206,7 +207,7 @@ impl DocItem { /// Format the function doc comments to make them /// into readable markdown. - pub fn format_comments(doc_comments: &[String]) -> String { + pub(crate) fn format_comments(doc_comments: &[String]) -> String { let doc_comments = doc_comments.to_vec(); let removed_extra_tokens = Self::remove_extra_tokens(doc_comments).join("\n"); let remove_comments = Self::fmt_doc_comments(removed_extra_tokens); @@ -215,7 +216,7 @@ impl DocItem { } /// Remove crate specific comments, like `rhai-autodocs:index`. - pub fn remove_extra_tokens(dc: Vec) -> Vec { + pub(crate) fn remove_extra_tokens(dc: Vec) -> Vec { dc.into_iter() .map(|s| { s.lines() @@ -227,7 +228,7 @@ impl DocItem { } /// Remove doc comments identifiers. - pub fn fmt_doc_comments(dc: String) -> String { + pub(crate) fn fmt_doc_comments(dc: String) -> String { dc.replace("/// ", "") .replace("///", "") .replace("/**", "") @@ -239,7 +240,7 @@ impl DocItem { /// markdown processors might not. /// Remove lines of code that starts with the '#' token, /// which are removed on rust docs automatically. - pub fn remove_test_code(doc_comments: &str) -> String { + pub(crate) fn remove_test_code(doc_comments: &str) -> String { let mut formatted = vec![]; let mut in_code_block = false; for line in doc_comments.lines() { diff --git a/src/glossary.rs b/src/glossary.rs index 7aeffc2..79c2110 100644 --- a/src/glossary.rs +++ b/src/glossary.rs @@ -23,7 +23,7 @@ pub struct ModuleGlossary { /// # Errors /// * Failed to generate function metadata as json. /// * Failed to parse module metadata. -pub fn generate_module_glossary( +pub(crate) fn generate_module_glossary( engine: &rhai::Engine, options: &Options, ) -> Result { diff --git a/src/lib.rs b/src/lib.rs index 17ce9aa..e7a2246 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,14 +1,14 @@ #![doc = include_str!("../README.md")] -pub mod custom_types; +mod custom_types; pub mod doc_item; -pub mod function; +mod function; pub mod glossary; pub mod module; pub use glossary::ModuleGlossary; pub use module::{ - options::{export, ItemsOrder, MarkdownProcessor, SectionFormat}, + options::{ItemsOrder, MarkdownProcessor, SectionFormat}, ModuleDocumentation, }; use serde_json::json; @@ -91,14 +91,14 @@ impl MDBookOptions { } pub mod generate { - /// Create a new builder to generate documentation for docusaurus from a [`ModuleDocumentation`] object. + /// Create a new builder to generate documentation for docusaurus from a [`super::module::ModuleDocumentation`] object. pub fn docusaurus() -> super::DocusaurusOptions { super::DocusaurusOptions::default() } - /// Create a new builder to generate documentation for mdbook from a [`ModuleDocumentation`] object. + /// Create a new builder to generate documentation for mdbook from a [`super::module::ModuleDocumentation`] object. pub fn mdbook() -> super::MDBookOptions { - super::MDBookOptions::default() + super::MDBookOptions } } @@ -128,3 +128,12 @@ fn generate( Ok(documentation) } + +pub mod export { + use crate::module::options::Options; + + /// Create new options used to configure docs generation. + pub fn options() -> Options { + Options::default() + } +} diff --git a/src/module/options.rs b/src/module/options.rs index f7a7bd3..0ecf357 100644 --- a/src/module/options.rs +++ b/src/module/options.rs @@ -26,13 +26,6 @@ pub struct Options { pub(crate) include_standard_packages: bool, } -pub mod export { - /// Create new options used to configure docs generation. - pub fn options() -> super::Options { - super::Options::default() - } -} - impl Options { /// Include the standard package functions and modules documentation /// in the generated documentation markdown. @@ -154,10 +147,6 @@ pub enum SectionFormat { Rust, /// Display sections using tabs that wraps all underlying /// documentation in them. - /// - /// NOTE: [`SectionFormat::fmt_sections`] is called after [`remove_test_code`], - /// so checking for code blocks and `#` line start is not required because it - /// was supposed to be removed. Tabs, }