diff --git a/extensions/scarb-doc/src/lib.rs b/extensions/scarb-doc/src/lib.rs index 9a3661a1a..63f8cb86b 100644 --- a/extensions/scarb-doc/src/lib.rs +++ b/extensions/scarb-doc/src/lib.rs @@ -35,6 +35,7 @@ pub fn generate_packages_information( let authors = package_metadata.manifest_metadata.authors.clone(); let project_config = get_project_config(metadata, package_metadata); + let crate_ = generate_language_elements_tree_for_package( package_metadata.name.clone(), project_config, diff --git a/extensions/scarb-doc/src/main.rs b/extensions/scarb-doc/src/main.rs index 140615c28..c5ba8e998 100644 --- a/extensions/scarb-doc/src/main.rs +++ b/extensions/scarb-doc/src/main.rs @@ -4,11 +4,13 @@ use scarb_doc::docs_generation::markdown::MarkdownContent; use scarb_doc::metadata::get_target_dir; use scarb_metadata::MetadataCommand; -use scarb_ui::args::PackagesFilter; +use scarb_ui::args::{PackagesFilter, ToEnvVars}; use scarb_doc::generate_packages_information; use scarb_doc::versioned_json_output::VersionedJsonOutput; +use scarb_ui::args::FeaturesSpec; + const OUTPUT_DIR: &str = "doc"; #[derive(Default, Debug, Clone, clap::ValueEnum)] @@ -33,6 +35,10 @@ struct Args { /// Specifies a format of generated files. #[arg(long, value_enum, default_value_t)] output_format: OutputFormat, + + /// Specifies features to enable. + #[command(flatten)] + pub features: FeaturesSpec, } fn main_inner() -> Result<()> { @@ -40,11 +46,11 @@ fn main_inner() -> Result<()> { let metadata = MetadataCommand::new() .inherit_stderr() + .envs(args.features.to_env_vars()) .exec() .context("metadata command failed")?; let metadata_for_packages = args.packages_filter.match_many(&metadata)?; let output_dir = get_target_dir(&metadata).join(OUTPUT_DIR); - let packages_information = generate_packages_information(&metadata, &metadata_for_packages); match args.output_format { diff --git a/extensions/scarb-doc/tests/code/code_1.cairo b/extensions/scarb-doc/tests/code/code_1.cairo new file mode 100644 index 000000000..4f5be0931 --- /dev/null +++ b/extensions/scarb-doc/tests/code/code_1.cairo @@ -0,0 +1,89 @@ +//! Fibonacci sequence calculator + +/// Main function that calculates the 16th Fibonacci number +fn main() -> u32 { + fib(16) +} + +/// use into_trait +use core::traits::Into as into_trait; +use core::traits::TryInto; + +/// FOO constant with value 42 +const FOO: u32 = 42; + +/// Calculate the nth Fibonacci number +/// +/// # Arguments +/// * `n` - The index of the Fibonacci number to calculate +/// +fn fib(mut n: u32) -> u32 { + let mut a: u32 = 0; + let mut b: u32 = 1; + while n != 0 { + n = n - 1; + let temp = b; + b = a + b; + a = temp; + }; + a +} + +/// Pair type alias for a tuple of two u32 values +type Pair = (u32, u32); + +/// Color enum with Red, Green, and Blue variants +enum Color { + /// Red color + Red: (), + /// Green color + Green: (), + /// Blue color + Blue: (), +} + +/// Shape trait for objects that have an area +trait Shape { + /// Constant for the shape type + const SHAPE_CONST: felt252; + + /// Type alias for a pair of shapes + type ShapePair; + + /// Calculate the area of the shape + fn area(self: T) -> u32; +} + +/// Circle struct with radius field +#[derive(Drop, Serde, PartialEq)] +struct Circle { + /// Radius of the circle + radius: u32, +} + +/// Implementation of the Shape trait for Circle +impl CircleShape of Shape { + /// Type alias for a pair of circles + type ShapePair = (Circle, Circle); + + /// Shape constant + const SHAPE_CONST: felt252 = 'xyz'; + + /// Implementation of the area method for Circle + fn area(self: Circle) -> u32 { + 3 * self.radius * self.radius + } +} + +/// Tests module +mod tests { + /// Imported fib function from the parent module + use super::fib as fib_function; + + /// Really + #[test] + /// works. + fn it_works() { + assert(fib_function(16) == 987, 'it works!'); + } +} diff --git a/extensions/scarb-doc/tests/code/code_2.cairo b/extensions/scarb-doc/tests/code/code_2.cairo new file mode 100644 index 000000000..e9246069f --- /dev/null +++ b/extensions/scarb-doc/tests/code/code_2.cairo @@ -0,0 +1,17 @@ +//! Sub-package code (without feature) + +/// Function that prints "test" to stdout with endline. +/// Can invoke it like that: +/// ```cairo +/// fn main() { +/// test(); +/// } +/// ``` +fn test() { + println!("test"); +} + +/// Main function that cairo runs as a binary entrypoint. +fn main() { + println!("hello_world"); +} diff --git a/extensions/scarb-doc/tests/code/code_3.cairo b/extensions/scarb-doc/tests/code/code_3.cairo new file mode 100644 index 000000000..661e814b8 --- /dev/null +++ b/extensions/scarb-doc/tests/code/code_3.cairo @@ -0,0 +1,19 @@ +//! Sub-package code (with feature) + +/// Function that prints "test" to stdout with endline. +/// Can invoke it like that: +/// ```cairo +/// fn main() { +/// test(); +/// } +/// ``` +#[cfg(feature: 'test_feature')] +/// This is a under feature attribute comment. +fn test() { + println!("test"); +} + +/// Main function that cairo runs as a binary entrypoint. +fn main() { + println!("hello_world"); +} diff --git a/extensions/scarb-doc/tests/code/code_4.cairo b/extensions/scarb-doc/tests/code/code_4.cairo new file mode 100644 index 000000000..cd9f09e73 --- /dev/null +++ b/extensions/scarb-doc/tests/code/code_4.cairo @@ -0,0 +1,100 @@ +//! Fibonacci sequence calculator + +/// Main function that calculates the 16th Fibonacci number +fn main() -> u32 { + fib(16) +} + +/// use into_trait +use core::traits::Into as into_trait; +use core::traits::TryInto; + +/// FOO constant with value 42 +const FOO: u32 = 42; + +/// Function that prints "test" to stdout with endline. +/// Can invoke it like that: +/// ```cairo +/// fn main() { +/// test(); +/// } +/// ``` +#[cfg(feature: "test_feature")] +fn test() { + println!("test"); +} +/// Calculate the nth Fibonacci number +/// +/// # Arguments +/// * `n` - The index of the Fibonacci number to calculate +/// +fn fib(mut n: u32) -> u32 { + let mut a: u32 = 0; + let mut b: u32 = 1; + while n != 0 { + n = n - 1; + let temp = b; + b = a + b; + a = temp; + }; + a +} + +/// Pair type alias for a tuple of two u32 values +type Pair = (u32, u32); + +/// Color enum with Red, Green, and Blue variants +enum Color { + /// Red color + Red: (), + /// Green color + Green: (), + /// Blue color + Blue: (), +} + +/// Shape trait for objects that have an area +trait Shape { + /// Constant for the shape type + const SHAPE_CONST: felt252; + + /// Type alias for a pair of shapes + type ShapePair; + + /// Calculate the area of the shape + fn area(self: T) -> u32; +} + +/// Circle struct with radius field +#[derive(Drop, Serde, PartialEq)] +struct Circle { + /// Radius of the circle + radius: u32, +} + +/// Implementation of the Shape trait for Circle +impl CircleShape of Shape { + /// Type alias for a pair of circles + type ShapePair = (Circle, Circle); + + /// Shape constant + const SHAPE_CONST: felt252 = 'xyz'; + + /// Implementation of the area method for Circle + fn area(self: Circle) -> u32 { + 3 * self.radius * self.radius + } +} + +/// Tests module +mod tests { + /// Imported fib function from the parent module + use super::fib as fib_function; + + /// Really + #[test] + /// works. + fn it_works() { + assert(fib_function(16) == 987, 'it works!'); + } +} diff --git a/extensions/scarb-doc/tests/data/hello_world/book.toml b/extensions/scarb-doc/tests/data/hello_world_no_features/book.toml similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/book.toml rename to extensions/scarb-doc/tests/data/hello_world_no_features/book.toml diff --git a/extensions/scarb-doc/tests/data/hello_world/src/SUMMARY.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/SUMMARY.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/SUMMARY.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/SUMMARY.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/constants.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/constants.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/constants.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/constants.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/enums.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/enums.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/enums.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/enums.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/free_functions.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/free_functions.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/free_functions.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/free_functions.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-Circle.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-Circle.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-Circle.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-Circle.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-CircleDrop.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-CircleDrop.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-CircleDrop.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-CircleDrop.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-CirclePartialEq.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-CirclePartialEq.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-CirclePartialEq.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-CirclePartialEq.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-CircleSerde.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-CircleSerde.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-CircleSerde.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-CircleSerde.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-CircleShape.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-CircleShape.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-CircleShape.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-CircleShape.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-Color.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-Color.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-Color.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-Color.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-FOO.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-FOO.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-FOO.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-FOO.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-Pair.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-Pair.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-Pair.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-Pair.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-Shape.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-Shape.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-Shape.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-Shape.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-fib.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-fib.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-fib.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-fib.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-main.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-main.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-main.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-main.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-tests-it_works.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-tests-it_works.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-tests-it_works.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-tests-it_works.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world-tests.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-tests.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world-tests.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world-tests.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/hello_world.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/hello_world.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/hello_world.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/impls.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/impls.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/impls.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/impls.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/modules.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/modules.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/modules.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/modules.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/structs.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/structs.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/structs.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/structs.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/traits.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/traits.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/traits.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/traits.md diff --git a/extensions/scarb-doc/tests/data/hello_world/src/type_aliases.md b/extensions/scarb-doc/tests/data/hello_world_no_features/src/type_aliases.md similarity index 100% rename from extensions/scarb-doc/tests/data/hello_world/src/type_aliases.md rename to extensions/scarb-doc/tests/data/hello_world_no_features/src/type_aliases.md diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/book.toml b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/book.toml new file mode 100644 index 000000000..413edcf45 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/book.toml @@ -0,0 +1,16 @@ +[book] +authors = [""] +language = "en" +multilingual = false +src = "src" +title = "hello_world_sub_package - Cairo" + +[output.html] +no-section-label = true + +[output.html.playground] +runnable = false + +[output.html.fold] +enable = true +level = 0 diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/SUMMARY.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/SUMMARY.md new file mode 100644 index 000000000..4601d6e5b --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/SUMMARY.md @@ -0,0 +1,12 @@ +# Summary + +- [Modules](./modules.md) + + - [hello_world_sub_package](./hello_world_sub_package.md) + +- [Free functions](./free_functions.md) + + - [test](./hello_world_sub_package-test.md) + + - [main](./hello_world_sub_package-main.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/free_functions.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/free_functions.md new file mode 100644 index 000000000..137c049b9 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/free_functions.md @@ -0,0 +1,6 @@ +# Free functions + +- [test](./hello_world_sub_package-test.md) + +- [main](./hello_world_sub_package-main.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/hello_world_sub_package-main.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/hello_world_sub_package-main.md new file mode 100644 index 000000000..5c91f6fdb --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/hello_world_sub_package-main.md @@ -0,0 +1,11 @@ +# main + +Main function that cairo runs as a binary entrypoint. + + +Fully qualified path: `hello_world_sub_package::main` + +```rust +fn main() +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/hello_world_sub_package-test.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/hello_world_sub_package-test.md new file mode 100644 index 000000000..8c8552900 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/hello_world_sub_package-test.md @@ -0,0 +1,18 @@ +# test + +Sub-package code (without feature) +Function that prints "test" to stdout with endline. +Can invoke it like that: +```cairo + fn main() { + test(); + } +``` + + +Fully qualified path: `hello_world_sub_package::test` + +```rust +fn test() +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/hello_world_sub_package.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/hello_world_sub_package.md new file mode 100644 index 000000000..298cacd69 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/hello_world_sub_package.md @@ -0,0 +1,10 @@ +# hello_world_sub_package + +Fully qualified path: `hello_world_sub_package` + +## Free functions + +- [test](./hello_world_sub_package-test.md) + +- [main](./hello_world_sub_package-main.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/modules.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/modules.md new file mode 100644 index 000000000..2ff4ca910 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_no_features/src/modules.md @@ -0,0 +1,4 @@ +# Modules + +- [hello_world_sub_package](./hello_world_sub_package.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/book.toml b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/book.toml new file mode 100644 index 000000000..413edcf45 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/book.toml @@ -0,0 +1,16 @@ +[book] +authors = [""] +language = "en" +multilingual = false +src = "src" +title = "hello_world_sub_package - Cairo" + +[output.html] +no-section-label = true + +[output.html.playground] +runnable = false + +[output.html.fold] +enable = true +level = 0 diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/SUMMARY.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/SUMMARY.md new file mode 100644 index 000000000..4601d6e5b --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/SUMMARY.md @@ -0,0 +1,12 @@ +# Summary + +- [Modules](./modules.md) + + - [hello_world_sub_package](./hello_world_sub_package.md) + +- [Free functions](./free_functions.md) + + - [test](./hello_world_sub_package-test.md) + + - [main](./hello_world_sub_package-main.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/free_functions.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/free_functions.md new file mode 100644 index 000000000..137c049b9 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/free_functions.md @@ -0,0 +1,6 @@ +# Free functions + +- [test](./hello_world_sub_package-test.md) + +- [main](./hello_world_sub_package-main.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/hello_world_sub_package-main.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/hello_world_sub_package-main.md new file mode 100644 index 000000000..5c91f6fdb --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/hello_world_sub_package-main.md @@ -0,0 +1,11 @@ +# main + +Main function that cairo runs as a binary entrypoint. + + +Fully qualified path: `hello_world_sub_package::main` + +```rust +fn main() +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/hello_world_sub_package-test.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/hello_world_sub_package-test.md new file mode 100644 index 000000000..f893bf604 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/hello_world_sub_package-test.md @@ -0,0 +1,19 @@ +# test + +Sub-package code (with feature) +Function that prints "test" to stdout with endline. +Can invoke it like that: +```cairo + fn main() { + test(); + } +``` +This is a under feature attribute comment. + + +Fully qualified path: `hello_world_sub_package::test` + +```rust +fn test() +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/hello_world_sub_package.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/hello_world_sub_package.md new file mode 100644 index 000000000..298cacd69 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/hello_world_sub_package.md @@ -0,0 +1,10 @@ +# hello_world_sub_package + +Fully qualified path: `hello_world_sub_package` + +## Free functions + +- [test](./hello_world_sub_package-test.md) + +- [main](./hello_world_sub_package-main.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/modules.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/modules.md new file mode 100644 index 000000000..2ff4ca910 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_with_features/src/modules.md @@ -0,0 +1,4 @@ +# Modules + +- [hello_world_sub_package](./hello_world_sub_package.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/book.toml b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/book.toml new file mode 100644 index 000000000..413edcf45 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/book.toml @@ -0,0 +1,16 @@ +[book] +authors = [""] +language = "en" +multilingual = false +src = "src" +title = "hello_world_sub_package - Cairo" + +[output.html] +no-section-label = true + +[output.html.playground] +runnable = false + +[output.html.fold] +enable = true +level = 0 diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/SUMMARY.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/SUMMARY.md new file mode 100644 index 000000000..1d33e2e30 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/SUMMARY.md @@ -0,0 +1,10 @@ +# Summary + +- [Modules](./modules.md) + + - [hello_world_sub_package](./hello_world_sub_package.md) + +- [Free functions](./free_functions.md) + + - [main](./hello_world_sub_package-main.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/free_functions.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/free_functions.md new file mode 100644 index 000000000..04c6c99d2 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/free_functions.md @@ -0,0 +1,4 @@ +# Free functions + +- [main](./hello_world_sub_package-main.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/hello_world_sub_package-main.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/hello_world_sub_package-main.md new file mode 100644 index 000000000..5c91f6fdb --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/hello_world_sub_package-main.md @@ -0,0 +1,11 @@ +# main + +Main function that cairo runs as a binary entrypoint. + + +Fully qualified path: `hello_world_sub_package::main` + +```rust +fn main() +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/hello_world_sub_package.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/hello_world_sub_package.md new file mode 100644 index 000000000..63af76998 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/hello_world_sub_package.md @@ -0,0 +1,8 @@ +# hello_world_sub_package + +Fully qualified path: `hello_world_sub_package` + +## Free functions + +- [main](./hello_world_sub_package-main.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/modules.md b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/modules.md new file mode 100644 index 000000000..2ff4ca910 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_sub_package_without_features/src/modules.md @@ -0,0 +1,4 @@ +# Modules + +- [hello_world_sub_package](./hello_world_sub_package.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/book.toml b/extensions/scarb-doc/tests/data/hello_world_with_features/book.toml new file mode 100644 index 000000000..b55144eb1 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/book.toml @@ -0,0 +1,16 @@ +[book] +authors = [""] +language = "en" +multilingual = false +src = "src" +title = "hello_world - Cairo" + +[output.html] +no-section-label = true + +[output.html.playground] +runnable = false + +[output.html.fold] +enable = true +level = 0 diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/SUMMARY.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/SUMMARY.md new file mode 100644 index 000000000..806d4fcdb --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/SUMMARY.md @@ -0,0 +1,48 @@ +# Summary + +- [Modules](./modules.md) + + - [hello_world](./hello_world.md) + + - [tests](./hello_world-tests.md) + +- [Constants](./constants.md) + + - [FOO](./hello_world-FOO.md) + +- [Free functions](./free_functions.md) + + - [main](./hello_world-main.md) + + - [test](./hello_world-test.md) + + - [fib](./hello_world-fib.md) + + - [it_works](./hello_world-tests-it_works.md) + +- [Structs](./structs.md) + + - [Circle](./hello_world-Circle.md) + +- [Enums](./enums.md) + + - [Color](./hello_world-Color.md) + +- [Type aliases](./type_aliases.md) + + - [Pair](./hello_world-Pair.md) + +- [Traits](./traits.md) + + - [Shape](./hello_world-Shape.md) + +- [Impls](./impls.md) + + - [CircleShape](./hello_world-CircleShape.md) + + - [CircleDrop](./hello_world-CircleDrop.md) + + - [CircleSerde](./hello_world-CircleSerde.md) + + - [CirclePartialEq](./hello_world-CirclePartialEq.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/constants.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/constants.md new file mode 100644 index 000000000..07df9a581 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/constants.md @@ -0,0 +1,4 @@ +# Constants + +- [FOO](./hello_world-FOO.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/enums.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/enums.md new file mode 100644 index 000000000..d578fe0e1 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/enums.md @@ -0,0 +1,4 @@ +# Enums + +- [Color](./hello_world-Color.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/free_functions.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/free_functions.md new file mode 100644 index 000000000..ba9819ce5 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/free_functions.md @@ -0,0 +1,10 @@ +# Free functions + +- [main](./hello_world-main.md) + +- [test](./hello_world-test.md) + +- [fib](./hello_world-fib.md) + +- [it_works](./hello_world-tests-it_works.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Circle.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Circle.md new file mode 100644 index 000000000..cf42f713a --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Circle.md @@ -0,0 +1,16 @@ +# Circle + +Circle struct with radius field + + +Fully qualified path: `hello_world::Circle` + +## Members + +### radius + +Radius of the circle + +Fully qualified path: `hello_world::Circle::radius` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CircleDrop.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CircleDrop.md new file mode 100644 index 000000000..550bcb91d --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CircleDrop.md @@ -0,0 +1,8 @@ +# CircleDrop + +Fully qualified path: `hello_world::CircleDrop` + +```rust +impl CircleDrop of core::traits::Drop; +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CirclePartialEq.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CirclePartialEq.md new file mode 100644 index 000000000..f22c631b6 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CirclePartialEq.md @@ -0,0 +1,19 @@ +# CirclePartialEq + +Fully qualified path: `hello_world::CirclePartialEq` + +```rust +impl CirclePartialEq of core::traits::PartialEq +``` + +## Impl functions + +### eq + +Fully qualified path: `hello_world::CirclePartialEq::eq` + +```rust +fn eq(lhs: @Circle, rhs: @Circle) -> bool +``` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CircleSerde.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CircleSerde.md new file mode 100644 index 000000000..28f86b2ae --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CircleSerde.md @@ -0,0 +1,28 @@ +# CircleSerde + +Fully qualified path: `hello_world::CircleSerde` + +```rust +impl CircleSerde of core::serde::Serde +``` + +## Impl functions + +### serialize + +Fully qualified path: `hello_world::CircleSerde::serialize` + +```rust +fn serialize(self: @Circle, ref output: core::array::Array) +``` + + +### deserialize + +Fully qualified path: `hello_world::CircleSerde::deserialize` + +```rust +fn deserialize(ref serialized: core::array::Span) -> core::option::Option +``` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CircleShape.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CircleShape.md new file mode 100644 index 000000000..d6997b9ec --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-CircleShape.md @@ -0,0 +1,53 @@ +# CircleShape + +Implementation of the Shape trait for Circle + + +Fully qualified path: `hello_world::CircleShape` + +```rust +impl CircleShape of Shape +``` + +## Impl constants + +### SHAPE_CONST + +Shape constant + + +Fully qualified path: `hello_world::CircleShape::SHAPE_CONST` + +```rust +const SHAPE_CONST: felt252 = 'xyz'; +``` + + +## Impl functions + +### area + +Implementation of the area method for Circle + + +Fully qualified path: `hello_world::CircleShape::area` + +```rust +fn area(self: Circle) -> u32 +``` + + +## Impl types + +### ShapePair + +Type alias for a pair of circles + + +Fully qualified path: `hello_world::CircleShape::ShapePair` + +```rust +type ShapePair = (Circle, Circle); +``` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Color.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Color.md new file mode 100644 index 000000000..316390f31 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Color.md @@ -0,0 +1,30 @@ +# Color + +Color enum with Red, Green, and Blue variants + + +Fully qualified path: `hello_world::Color` + +## Variants + +### Red + +Red color + +Fully qualified path: `hello_world::Color::Red` + + +### Green + +Green color + +Fully qualified path: `hello_world::Color::Green` + + +### Blue + +Blue color + +Fully qualified path: `hello_world::Color::Blue` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-FOO.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-FOO.md new file mode 100644 index 000000000..da65e8594 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-FOO.md @@ -0,0 +1,11 @@ +# FOO + +FOO constant with value 42 + + +Fully qualified path: `hello_world::FOO` + +```rust +const FOO: u32 = 42; +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Pair.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Pair.md new file mode 100644 index 000000000..f0d81932c --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Pair.md @@ -0,0 +1,11 @@ +# Pair + +Pair type alias for a tuple of two u32 values + + +Fully qualified path: `hello_world::Pair` + +```rust +type Pair = (u32, u32); +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Shape.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Shape.md new file mode 100644 index 000000000..b08696b6f --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-Shape.md @@ -0,0 +1,45 @@ +# Shape + +Shape trait for objects that have an area + + +Fully qualified path: `hello_world::Shape` + +```rust +trait Shape +``` + +## Trait constants + +### SHAPE_CONST + +Constant for the shape type + + +Fully qualified path: `hello_world::Shape::SHAPE_CONST` + + +## Trait functions + +### area + +Calculate the area of the shape + + +Fully qualified path: `Shape::area` + +```rust +fn area(self: T) -> u32 +``` + + +## Trait types + +### ShapePair + +Type alias for a pair of shapes + + +Fully qualified path: `hello_world::Shape::ShapePair` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-fib.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-fib.md new file mode 100644 index 000000000..dfcf68703 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-fib.md @@ -0,0 +1,14 @@ +# fib + +Calculate the nth Fibonacci number + +# Arguments +* `n` - The index of the Fibonacci number to calculate + + +Fully qualified path: `hello_world::fib` + +```rust +fn fib(mut n: u32) -> u32 +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-main.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-main.md new file mode 100644 index 000000000..ad0b72cf7 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-main.md @@ -0,0 +1,12 @@ +# main + +Fibonacci sequence calculator +Main function that calculates the 16th Fibonacci number + + +Fully qualified path: `hello_world::main` + +```rust +fn main() -> u32 +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-test.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-test.md new file mode 100644 index 000000000..994927fb3 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-test.md @@ -0,0 +1,17 @@ +# test + +Function that prints "test" to stdout with endline. +Can invoke it like that: +```cairo + fn main() { + test(); + } +``` + + +Fully qualified path: `hello_world::test` + +```rust +fn test() +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-tests-it_works.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-tests-it_works.md new file mode 100644 index 000000000..f78d405fe --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-tests-it_works.md @@ -0,0 +1,12 @@ +# it_works + +Really +works. + + +Fully qualified path: `hello_world::tests::it_works` + +```rust +fn it_works() +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-tests.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-tests.md new file mode 100644 index 000000000..f72f03ff7 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world-tests.md @@ -0,0 +1,11 @@ +# tests + +Tests module + + +Fully qualified path: `hello_world::tests` + +## Free functions + +- [it_works](./hello_world-tests-it_works.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world.md new file mode 100644 index 000000000..0dcbc9921 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/hello_world.md @@ -0,0 +1,46 @@ +# hello_world + +Fully qualified path: `hello_world` + +## Modules + +- [tests](./hello_world-tests.md) + +## Constants + +- [FOO](./hello_world-FOO.md) + +## Free functions + +- [main](./hello_world-main.md) + +- [test](./hello_world-test.md) + +- [fib](./hello_world-fib.md) + +## Structs + +- [Circle](./hello_world-Circle.md) + +## Enums + +- [Color](./hello_world-Color.md) + +## Type aliases + +- [Pair](./hello_world-Pair.md) + +## Traits + +- [Shape](./hello_world-Shape.md) + +## Impls + +- [CircleShape](./hello_world-CircleShape.md) + +- [CircleDrop](./hello_world-CircleDrop.md) + +- [CircleSerde](./hello_world-CircleSerde.md) + +- [CirclePartialEq](./hello_world-CirclePartialEq.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/impls.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/impls.md new file mode 100644 index 000000000..d76703860 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/impls.md @@ -0,0 +1,10 @@ +# Impls + +- [CircleShape](./hello_world-CircleShape.md) + +- [CircleDrop](./hello_world-CircleDrop.md) + +- [CircleSerde](./hello_world-CircleSerde.md) + +- [CirclePartialEq](./hello_world-CirclePartialEq.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/modules.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/modules.md new file mode 100644 index 000000000..72d5f60af --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/modules.md @@ -0,0 +1,6 @@ +# Modules + +- [hello_world](./hello_world.md) + +- [tests](./hello_world-tests.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/structs.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/structs.md new file mode 100644 index 000000000..48d05f738 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/structs.md @@ -0,0 +1,4 @@ +# Structs + +- [Circle](./hello_world-Circle.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/traits.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/traits.md new file mode 100644 index 000000000..0e3d7bf72 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/traits.md @@ -0,0 +1,4 @@ +# Traits + +- [Shape](./hello_world-Shape.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_with_features/src/type_aliases.md b/extensions/scarb-doc/tests/data/hello_world_with_features/src/type_aliases.md new file mode 100644 index 000000000..f92762406 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_with_features/src/type_aliases.md @@ -0,0 +1,4 @@ +# Type aliases + +- [Pair](./hello_world-Pair.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/book.toml b/extensions/scarb-doc/tests/data/hello_world_without_features/book.toml new file mode 100644 index 000000000..b55144eb1 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/book.toml @@ -0,0 +1,16 @@ +[book] +authors = [""] +language = "en" +multilingual = false +src = "src" +title = "hello_world - Cairo" + +[output.html] +no-section-label = true + +[output.html.playground] +runnable = false + +[output.html.fold] +enable = true +level = 0 diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/SUMMARY.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/SUMMARY.md new file mode 100644 index 000000000..6ff32f1ef --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/SUMMARY.md @@ -0,0 +1,46 @@ +# Summary + +- [Modules](./modules.md) + + - [hello_world](./hello_world.md) + + - [tests](./hello_world-tests.md) + +- [Constants](./constants.md) + + - [FOO](./hello_world-FOO.md) + +- [Free functions](./free_functions.md) + + - [main](./hello_world-main.md) + + - [fib](./hello_world-fib.md) + + - [it_works](./hello_world-tests-it_works.md) + +- [Structs](./structs.md) + + - [Circle](./hello_world-Circle.md) + +- [Enums](./enums.md) + + - [Color](./hello_world-Color.md) + +- [Type aliases](./type_aliases.md) + + - [Pair](./hello_world-Pair.md) + +- [Traits](./traits.md) + + - [Shape](./hello_world-Shape.md) + +- [Impls](./impls.md) + + - [CircleShape](./hello_world-CircleShape.md) + + - [CircleDrop](./hello_world-CircleDrop.md) + + - [CircleSerde](./hello_world-CircleSerde.md) + + - [CirclePartialEq](./hello_world-CirclePartialEq.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/constants.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/constants.md new file mode 100644 index 000000000..07df9a581 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/constants.md @@ -0,0 +1,4 @@ +# Constants + +- [FOO](./hello_world-FOO.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/enums.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/enums.md new file mode 100644 index 000000000..d578fe0e1 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/enums.md @@ -0,0 +1,4 @@ +# Enums + +- [Color](./hello_world-Color.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/free_functions.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/free_functions.md new file mode 100644 index 000000000..e83f0ef37 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/free_functions.md @@ -0,0 +1,8 @@ +# Free functions + +- [main](./hello_world-main.md) + +- [fib](./hello_world-fib.md) + +- [it_works](./hello_world-tests-it_works.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Circle.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Circle.md new file mode 100644 index 000000000..cf42f713a --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Circle.md @@ -0,0 +1,16 @@ +# Circle + +Circle struct with radius field + + +Fully qualified path: `hello_world::Circle` + +## Members + +### radius + +Radius of the circle + +Fully qualified path: `hello_world::Circle::radius` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CircleDrop.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CircleDrop.md new file mode 100644 index 000000000..550bcb91d --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CircleDrop.md @@ -0,0 +1,8 @@ +# CircleDrop + +Fully qualified path: `hello_world::CircleDrop` + +```rust +impl CircleDrop of core::traits::Drop; +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CirclePartialEq.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CirclePartialEq.md new file mode 100644 index 000000000..f22c631b6 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CirclePartialEq.md @@ -0,0 +1,19 @@ +# CirclePartialEq + +Fully qualified path: `hello_world::CirclePartialEq` + +```rust +impl CirclePartialEq of core::traits::PartialEq +``` + +## Impl functions + +### eq + +Fully qualified path: `hello_world::CirclePartialEq::eq` + +```rust +fn eq(lhs: @Circle, rhs: @Circle) -> bool +``` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CircleSerde.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CircleSerde.md new file mode 100644 index 000000000..28f86b2ae --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CircleSerde.md @@ -0,0 +1,28 @@ +# CircleSerde + +Fully qualified path: `hello_world::CircleSerde` + +```rust +impl CircleSerde of core::serde::Serde +``` + +## Impl functions + +### serialize + +Fully qualified path: `hello_world::CircleSerde::serialize` + +```rust +fn serialize(self: @Circle, ref output: core::array::Array) +``` + + +### deserialize + +Fully qualified path: `hello_world::CircleSerde::deserialize` + +```rust +fn deserialize(ref serialized: core::array::Span) -> core::option::Option +``` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CircleShape.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CircleShape.md new file mode 100644 index 000000000..d6997b9ec --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-CircleShape.md @@ -0,0 +1,53 @@ +# CircleShape + +Implementation of the Shape trait for Circle + + +Fully qualified path: `hello_world::CircleShape` + +```rust +impl CircleShape of Shape +``` + +## Impl constants + +### SHAPE_CONST + +Shape constant + + +Fully qualified path: `hello_world::CircleShape::SHAPE_CONST` + +```rust +const SHAPE_CONST: felt252 = 'xyz'; +``` + + +## Impl functions + +### area + +Implementation of the area method for Circle + + +Fully qualified path: `hello_world::CircleShape::area` + +```rust +fn area(self: Circle) -> u32 +``` + + +## Impl types + +### ShapePair + +Type alias for a pair of circles + + +Fully qualified path: `hello_world::CircleShape::ShapePair` + +```rust +type ShapePair = (Circle, Circle); +``` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Color.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Color.md new file mode 100644 index 000000000..316390f31 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Color.md @@ -0,0 +1,30 @@ +# Color + +Color enum with Red, Green, and Blue variants + + +Fully qualified path: `hello_world::Color` + +## Variants + +### Red + +Red color + +Fully qualified path: `hello_world::Color::Red` + + +### Green + +Green color + +Fully qualified path: `hello_world::Color::Green` + + +### Blue + +Blue color + +Fully qualified path: `hello_world::Color::Blue` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-FOO.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-FOO.md new file mode 100644 index 000000000..da65e8594 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-FOO.md @@ -0,0 +1,11 @@ +# FOO + +FOO constant with value 42 + + +Fully qualified path: `hello_world::FOO` + +```rust +const FOO: u32 = 42; +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Pair.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Pair.md new file mode 100644 index 000000000..f0d81932c --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Pair.md @@ -0,0 +1,11 @@ +# Pair + +Pair type alias for a tuple of two u32 values + + +Fully qualified path: `hello_world::Pair` + +```rust +type Pair = (u32, u32); +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Shape.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Shape.md new file mode 100644 index 000000000..b08696b6f --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-Shape.md @@ -0,0 +1,45 @@ +# Shape + +Shape trait for objects that have an area + + +Fully qualified path: `hello_world::Shape` + +```rust +trait Shape +``` + +## Trait constants + +### SHAPE_CONST + +Constant for the shape type + + +Fully qualified path: `hello_world::Shape::SHAPE_CONST` + + +## Trait functions + +### area + +Calculate the area of the shape + + +Fully qualified path: `Shape::area` + +```rust +fn area(self: T) -> u32 +``` + + +## Trait types + +### ShapePair + +Type alias for a pair of shapes + + +Fully qualified path: `hello_world::Shape::ShapePair` + + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-fib.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-fib.md new file mode 100644 index 000000000..dfcf68703 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-fib.md @@ -0,0 +1,14 @@ +# fib + +Calculate the nth Fibonacci number + +# Arguments +* `n` - The index of the Fibonacci number to calculate + + +Fully qualified path: `hello_world::fib` + +```rust +fn fib(mut n: u32) -> u32 +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-main.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-main.md new file mode 100644 index 000000000..6b00b8f21 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-main.md @@ -0,0 +1,11 @@ +# main + +Main function that calculates the 16th Fibonacci number + + +Fully qualified path: `hello_world::main` + +```rust +fn main() -> u32 +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-tests-it_works.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-tests-it_works.md new file mode 100644 index 000000000..f78d405fe --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-tests-it_works.md @@ -0,0 +1,12 @@ +# it_works + +Really +works. + + +Fully qualified path: `hello_world::tests::it_works` + +```rust +fn it_works() +``` + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-tests.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-tests.md new file mode 100644 index 000000000..f72f03ff7 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world-tests.md @@ -0,0 +1,11 @@ +# tests + +Tests module + + +Fully qualified path: `hello_world::tests` + +## Free functions + +- [it_works](./hello_world-tests-it_works.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world.md new file mode 100644 index 000000000..b17728f49 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/hello_world.md @@ -0,0 +1,44 @@ +# hello_world + +Fully qualified path: `hello_world` + +## Modules + +- [tests](./hello_world-tests.md) + +## Constants + +- [FOO](./hello_world-FOO.md) + +## Free functions + +- [main](./hello_world-main.md) + +- [fib](./hello_world-fib.md) + +## Structs + +- [Circle](./hello_world-Circle.md) + +## Enums + +- [Color](./hello_world-Color.md) + +## Type aliases + +- [Pair](./hello_world-Pair.md) + +## Traits + +- [Shape](./hello_world-Shape.md) + +## Impls + +- [CircleShape](./hello_world-CircleShape.md) + +- [CircleDrop](./hello_world-CircleDrop.md) + +- [CircleSerde](./hello_world-CircleSerde.md) + +- [CirclePartialEq](./hello_world-CirclePartialEq.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/impls.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/impls.md new file mode 100644 index 000000000..d76703860 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/impls.md @@ -0,0 +1,10 @@ +# Impls + +- [CircleShape](./hello_world-CircleShape.md) + +- [CircleDrop](./hello_world-CircleDrop.md) + +- [CircleSerde](./hello_world-CircleSerde.md) + +- [CirclePartialEq](./hello_world-CirclePartialEq.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/modules.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/modules.md new file mode 100644 index 000000000..72d5f60af --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/modules.md @@ -0,0 +1,6 @@ +# Modules + +- [hello_world](./hello_world.md) + +- [tests](./hello_world-tests.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/structs.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/structs.md new file mode 100644 index 000000000..48d05f738 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/structs.md @@ -0,0 +1,4 @@ +# Structs + +- [Circle](./hello_world-Circle.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/traits.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/traits.md new file mode 100644 index 000000000..0e3d7bf72 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/traits.md @@ -0,0 +1,4 @@ +# Traits + +- [Shape](./hello_world-Shape.md) + diff --git a/extensions/scarb-doc/tests/data/hello_world_without_features/src/type_aliases.md b/extensions/scarb-doc/tests/data/hello_world_without_features/src/type_aliases.md new file mode 100644 index 000000000..f92762406 --- /dev/null +++ b/extensions/scarb-doc/tests/data/hello_world_without_features/src/type_aliases.md @@ -0,0 +1,4 @@ +# Type aliases + +- [Pair](./hello_world-Pair.md) + diff --git a/extensions/scarb-doc/tests/features.rs b/extensions/scarb-doc/tests/features.rs new file mode 100644 index 000000000..b61010fa9 --- /dev/null +++ b/extensions/scarb-doc/tests/features.rs @@ -0,0 +1,448 @@ +//! Run `UPDATE_EXPECT=1 cargo test` to fix the tests. + +use assert_fs::prelude::PathChild; +use assert_fs::TempDir; +use indoc::{formatdoc, indoc}; +use scarb_test_support::workspace_builder::WorkspaceBuilder; + +use scarb_test_support::command::Scarb; +use scarb_test_support::project_builder::ProjectBuilder; + +const EXPECTED_ROOT_PACKAGE_NO_FEATURES_PATH: &str = "tests/data/hello_world_no_features"; +const EXPECTED_ROOT_PACKAGE_WITH_FEATURES_PATH: &str = "tests/data/hello_world_with_features"; +const EXPECTED_SUB_PACKAGE_NO_FEATURES_PATH: &str = + "tests/data/hello_world_sub_package_no_features"; +const EXPECTED_SUB_PACKAGE_WITH_FEATURES_PATH: &str = + "tests/data/hello_world_sub_package_with_features"; + +mod target; +use target::TargetChecker; + +const FEATURE_NAME: &str = "test_feature"; + +const FIBONACCI_CODE_WITHOUT_FEATURE: &str = include_str!("code/code_1.cairo"); +const FIBONACCI_CODE_WITH_FEATURE: &str = include_str!("code/code_4.cairo"); +const COMMON_CODE_WITHOUT_FEATURE: &str = include_str!("code/code_2.cairo"); +const COMMON_CODE_WITH_FEATURE: &str = include_str!("code/code_3.cairo"); + +#[test] +fn test_workspace_no_features() { + let root_dir = TempDir::new().unwrap(); + let child_dir = root_dir.child("hello_world_sub_package"); + + let root = ProjectBuilder::start() + .name("hello_world") + .lib_cairo(FIBONACCI_CODE_WITHOUT_FEATURE); + + WorkspaceBuilder::start() + .add_member("hello_world_sub_package") + .package(root) + .build(&root_dir); + + ProjectBuilder::start() + .name("hello_world_sub_package") + .lib_cairo(COMMON_CODE_WITHOUT_FEATURE) + .build(&child_dir); + + Scarb::quick_snapbox() + .arg("doc") + .args(["--output-format", "markdown", "--workspace"]) + .current_dir(&root_dir) + .assert() + .success(); + + TargetChecker::default() + .actual( + root_dir + .path() + .join("target/doc/hello_world") + .to_str() + .unwrap(), + ) + .expected(EXPECTED_ROOT_PACKAGE_NO_FEATURES_PATH) + .assert_all_files_match(); + + TargetChecker::default() + .actual( + root_dir + .path() + .join("target/doc/hello_world_sub_package") + .to_str() + .unwrap(), + ) + .expected(EXPECTED_SUB_PACKAGE_NO_FEATURES_PATH) + .assert_all_files_match(); +} + +#[test] +fn test_workspace_without_features_in_manifest() { + let root_dir = TempDir::new().unwrap(); + let child_dir = root_dir.child("hello_world_sub_package"); + + let root = ProjectBuilder::start() + .name("hello_world") + .lib_cairo(FIBONACCI_CODE_WITHOUT_FEATURE); + + WorkspaceBuilder::start() + .add_member("hello_world_sub_package") + .package(root) + .build(&root_dir); + + ProjectBuilder::start() + .name("hello_world_sub_package") + .lib_cairo(COMMON_CODE_WITHOUT_FEATURE) + .build(&child_dir); + + let snapbox = Scarb::quick_snapbox() + .env("RUST_BACKTRACE", "0") + .arg("doc") + .args([ + "--output-format", + "markdown", + "--workspace", + "--features", + FEATURE_NAME, + ]) + .current_dir(&root_dir) + .assert() + .failure(); + + #[cfg(windows)] + snapbox.stdout_matches(indoc! {r#" + error: metadata command failed: `scarb metadata` exited with error + + stdout: + error: no features in manifest + note: to use features, you need to define [features] section in Scarb.toml + + stderr: + + error: process did not exit successfully: exit code: 1 + "#}); + + #[cfg(not(windows))] + snapbox.stdout_matches(indoc! {r#" + error: metadata command failed: `scarb metadata` exited with error + + stdout: + error: no features in manifest + note: to use features, you need to define [features] section in Scarb.toml + + stderr: + + "#}); +} + +#[test] +fn test_workspace_with_working_feature_in_root_and_sub_package() { + let root_dir = TempDir::new().unwrap(); + let child_dir = root_dir.child("hello_world_sub_package"); + + let root = ProjectBuilder::start() + .name("hello_world") + .lib_cairo(FIBONACCI_CODE_WITH_FEATURE); + + WorkspaceBuilder::start() + .add_member("hello_world_sub_package") + .manifest_extra(formatdoc! {r#" + [features] + {feature_name} = [] + "#, + feature_name = FEATURE_NAME, + }) + .package(root) + .build(&root_dir); + + ProjectBuilder::start() + .name("hello_world_sub_package") + .manifest_extra(formatdoc! {r#" + [features] + {feature_name} = [] + "#, + feature_name = FEATURE_NAME + }) + .lib_cairo(COMMON_CODE_WITH_FEATURE) + .build(&child_dir); + + Scarb::quick_snapbox() + .arg("doc") + .args([ + "--workspace", + "--features", + FEATURE_NAME, + "--output-format", + "markdown", + ]) + .current_dir(&root_dir) + .assert() + .success(); + + TargetChecker::default() + .actual( + root_dir + .path() + .join("target/doc/hello_world") + .to_str() + .unwrap(), + ) + .expected(EXPECTED_ROOT_PACKAGE_WITH_FEATURES_PATH) + .assert_all_files_match(); + + TargetChecker::default() + .actual( + root_dir + .path() + .join("target/doc/hello_world_sub_package") + .to_str() + .unwrap(), + ) + .expected(EXPECTED_SUB_PACKAGE_WITH_FEATURES_PATH) + .assert_all_files_match(); +} + +#[test] +fn test_workspace_with_working_feature_in_root_only() { + let root_dir = TempDir::new().unwrap(); + let child_dir = root_dir.child("hello_world_sub_package"); + + let root = ProjectBuilder::start() + .name("hello_world") + .lib_cairo(FIBONACCI_CODE_WITH_FEATURE); + + WorkspaceBuilder::start() + .add_member("hello_world_sub_package") + .manifest_extra(formatdoc! {r#" + [features] + {feature_name} = [] + "#, + feature_name = FEATURE_NAME + }) + .package(root) + .build(&root_dir); + + ProjectBuilder::start() + .name("hello_world_sub_package") + .lib_cairo(COMMON_CODE_WITH_FEATURE) + .build(&child_dir); + + let snapbox = Scarb::quick_snapbox() + .env("RUST_BACKTRACE", "0") + .arg("doc") + .args([ + "--workspace", + "--features", + FEATURE_NAME, + "--output-format", + "markdown", + ]) + .current_dir(&root_dir) + .assert() + .failure(); + + #[cfg(windows)] + snapbox.stdout_matches(indoc! {r#" + error: metadata command failed: `scarb metadata` exited with error + + stdout: + error: no features in manifest + note: to use features, you need to define [features] section in Scarb.toml + + stderr: + + error: process did not exit successfully: exit code: 1 + "#}); + + #[cfg(not(windows))] + snapbox.stdout_matches(indoc! {r#" + error: metadata command failed: `scarb metadata` exited with error + + stdout: + error: no features in manifest + note: to use features, you need to define [features] section in Scarb.toml + + stderr: + + "#}); +} + +#[test] +fn test_workspace_with_working_feature_in_sub_package_only() { + let root_dir = TempDir::new().unwrap(); + let child_dir = root_dir.child("hello_world_sub_package"); + + let root = ProjectBuilder::start() + .name("hello_world") + .lib_cairo(FIBONACCI_CODE_WITH_FEATURE); + + WorkspaceBuilder::start() + .add_member("hello_world_sub_package") + .package(root) + .build(&root_dir); + + ProjectBuilder::start() + .name("hello_world_sub_package") + .manifest_extra(formatdoc! {r#" + [features] + {feature_name} = [] + "#, + feature_name = FEATURE_NAME + }) + .lib_cairo(COMMON_CODE_WITH_FEATURE) + .build(&child_dir); + + let snapbox = Scarb::quick_snapbox() + .env("RUST_BACKTRACE", "0") + .arg("doc") + .args([ + "--workspace", + "--features", + FEATURE_NAME, + "--output-format", + "markdown", + ]) + .current_dir(&root_dir) + .assert() + .failure(); + + #[cfg(windows)] + snapbox.stdout_matches(indoc! {r#" + error: metadata command failed: `scarb metadata` exited with error + + stdout: + error: no features in manifest + note: to use features, you need to define [features] section in Scarb.toml + + stderr: + + error: process did not exit successfully: exit code: 1 + "#}); + + #[cfg(not(windows))] + snapbox.stdout_matches(indoc! {r#" + error: metadata command failed: `scarb metadata` exited with error + + stdout: + error: no features in manifest + note: to use features, you need to define [features] section in Scarb.toml + + stderr: + + "#}); +} + +#[test] +fn test_workspace_without_features_in_manifest_and_present_in_sub_package_code() { + let root_dir = TempDir::new().unwrap(); + let child_dir = root_dir.child("hello_world_sub_package"); + + let root = ProjectBuilder::start() + .name("hello_world") + .lib_cairo(FIBONACCI_CODE_WITHOUT_FEATURE); + + WorkspaceBuilder::start() + .add_member("hello_world_sub_package") + .package(root) + .build(&root_dir); + + ProjectBuilder::start() + .name("hello_world_sub_package") + .lib_cairo(COMMON_CODE_WITH_FEATURE) + .build(&child_dir); + + let snapbox = Scarb::quick_snapbox() + .env("RUST_BACKTRACE", "0") + .arg("doc") + .args([ + "--output-format", + "markdown", + "--workspace", + "--features", + FEATURE_NAME, + ]) + .current_dir(&root_dir) + .assert() + .failure(); + #[cfg(windows)] + snapbox.stdout_matches(indoc! {r#" + error: metadata command failed: `scarb metadata` exited with error + + stdout: + error: no features in manifest + note: to use features, you need to define [features] section in Scarb.toml + + stderr: + + error: process did not exit successfully: exit code: 1 + "#}); + + #[cfg(not(windows))] + snapbox.stdout_matches(indoc! {r#" + error: metadata command failed: `scarb metadata` exited with error + + stdout: + error: no features in manifest + note: to use features, you need to define [features] section in Scarb.toml + + stderr: + + "#}); +} + +#[test] +fn test_workspace_without_features_in_manifest_and_present_in_root_package_code() { + let root_dir = TempDir::new().unwrap(); + let child_dir = root_dir.child("hello_world_sub_package"); + + let root = ProjectBuilder::start() + .name("hello_world") + .lib_cairo(FIBONACCI_CODE_WITH_FEATURE); + + WorkspaceBuilder::start() + .add_member("hello_world_sub_package") + .package(root) + .build(&root_dir); + + ProjectBuilder::start() + .name("hello_world_sub_package") + .lib_cairo(COMMON_CODE_WITH_FEATURE) + .build(&child_dir); + + let snapbox = Scarb::quick_snapbox() + .env("RUST_BACKTRACE", "0") + .arg("doc") + .args([ + "--output-format", + "markdown", + "--workspace", + "--features", + FEATURE_NAME, + ]) + .current_dir(&root_dir) + .assert() + .failure(); + + #[cfg(windows)] + snapbox.stdout_matches(indoc! {r#" + error: metadata command failed: `scarb metadata` exited with error + + stdout: + error: no features in manifest + note: to use features, you need to define [features] section in Scarb.toml + + stderr: + + error: process did not exit successfully: exit code: 1 + "#}); + + #[cfg(not(windows))] + snapbox.stdout_matches(indoc! {r#" + error: metadata command failed: `scarb metadata` exited with error + + stdout: + error: no features in manifest + note: to use features, you need to define [features] section in Scarb.toml + + stderr: + + "#}); +} diff --git a/extensions/scarb-doc/tests/output_format.rs b/extensions/scarb-doc/tests/output_format.rs new file mode 100644 index 000000000..b6cbf9778 --- /dev/null +++ b/extensions/scarb-doc/tests/output_format.rs @@ -0,0 +1,56 @@ +//! Run `UPDATE_EXPECT=1 cargo test` to fix the tests. + +use std::fs; + +use assert_fs::TempDir; +use expect_test::expect_file; +use scarb_test_support::{command::Scarb, project_builder::ProjectBuilder}; + +mod target; +use target::TargetChecker; + +const EXPECTED_ROOT_PACKAGE_NO_FEATURES_PATH: &str = "tests/data/hello_world_no_features"; + +const FIBONACCI_CODE_WITHOUT_FEATURE: &str = include_str!("code/code_1.cairo"); + +#[test] +fn json_output() { + let t = TempDir::new().unwrap(); + ProjectBuilder::start() + .name("hello_world") + .lib_cairo(FIBONACCI_CODE_WITHOUT_FEATURE) + .build(&t); + + Scarb::quick_snapbox() + .arg("doc") + .args(["--output-format", "json"]) + .current_dir(&t) + .assert() + .success(); + + let serialized_crates = fs::read_to_string(t.path().join("target/doc/output.json")) + .expect("Failed to read from file"); + let expected = expect_file!["./data/json_output_test_data.json"]; + expected.assert_eq(&serialized_crates); +} + +#[test] +fn markdown_output() { + let t = TempDir::new().unwrap(); + ProjectBuilder::start() + .name("hello_world") + .lib_cairo(FIBONACCI_CODE_WITHOUT_FEATURE) + .build(&t); + + Scarb::quick_snapbox() + .arg("doc") + .args(["--output-format", "markdown"]) + .current_dir(&t) + .assert() + .success(); + + TargetChecker::default() + .actual(t.path().join("target/doc/hello_world").to_str().unwrap()) + .expected(EXPECTED_ROOT_PACKAGE_NO_FEATURES_PATH) + .assert_all_files_match(); +} diff --git a/extensions/scarb-doc/tests/target.rs b/extensions/scarb-doc/tests/target.rs new file mode 100644 index 000000000..f2e4b7644 --- /dev/null +++ b/extensions/scarb-doc/tests/target.rs @@ -0,0 +1,95 @@ +use expect_test::expect_file; +use indoc::formatdoc; +use scarb_test_support::fsx; +use std::{fs, iter::zip}; +use walkdir::WalkDir; + +#[derive(Default)] +pub struct TargetChecker { + actual: Option, + expected: Option, +} + +impl TargetChecker { + pub fn actual(mut self, path: &str) -> Self { + assert!(Self::check_if_directory(path)); + self.actual = Some(WalkDir::new(path).sort_by_file_name()); + self + } + + pub fn expected(mut self, path: &str) -> Self { + assert!(Self::check_if_directory(path)); + self.expected = Some(WalkDir::new(path).sort_by_file_name()); + self + } + + pub fn assert_all_files_match(self) { + if self.actual.is_none() { + panic!("error: actual target directory was not set."); + } + + if self.expected.is_none() { + panic!("error: expected target directory was not set."); + } + + let actual_files: Vec<_> = self + .actual + .unwrap() + .into_iter() + .filter_map(Result::ok) + .collect(); + + let expected_files: Vec<_> = self + .expected + .unwrap() + .into_iter() + .filter_map(Result::ok) + .collect(); + + if actual_files.len() != expected_files.len() { + panic!( + "{}", + formatdoc! { + " + error: actual and expected target directories have different number of entries + actual: {actual} + expected: {expected} + ", + actual = actual_files.len(), + expected = expected_files.len() + } + ); + }; + + for (actual_dir_entry, expected_dir_entry) in zip(actual_files, expected_files) { + if expected_dir_entry.file_type().is_file() { + assert!(actual_dir_entry.file_type().is_file()); + + let content = fs::read_to_string(actual_dir_entry.path()).unwrap(); + + let expect_file = + expect_file![fsx::canonicalize(expected_dir_entry.path()).unwrap()]; + expect_file.assert_eq(&content); + } + } + } + + fn check_if_directory(path: &str) -> bool { + match fs::metadata(path) { + Ok(metadata) => { + if metadata.is_file() { + panic!( + "Given path ({wrong_path}) is not a directory.", + wrong_path = path + ) + } + } + Err(e) => panic!( + "Failed to get metadata for {wrong_path}, {error}", + wrong_path = path, + error = e + ), + } + true + } +} diff --git a/extensions/scarb-doc/tests/test.rs b/extensions/scarb-doc/tests/test.rs deleted file mode 100644 index 71d539b1e..000000000 --- a/extensions/scarb-doc/tests/test.rs +++ /dev/null @@ -1,161 +0,0 @@ -//! Run `UPDATE_EXPECT=1 cargo test` to fix the tests. - -use assert_fs::TempDir; -use expect_test::expect_file; -use indoc::indoc; -use std::fs; -use std::iter::zip; -use walkdir::WalkDir; - -use scarb_test_support::command::Scarb; -use scarb_test_support::fsx; -use scarb_test_support::project_builder::ProjectBuilder; - -const CODE: &str = indoc! { - r#" - //! Fibonacci sequence calculator - - - /// Main function that calculates the 16th Fibonacci number - fn main() -> u32 { - fib(16) - } - - /// use into_trait - use core::traits::Into as into_trait; - use core::traits::TryInto; - - /// FOO constant with value 42 - const FOO: u32 = 42; - - /// Calculate the nth Fibonacci number - /// - /// # Arguments - /// * `n` - The index of the Fibonacci number to calculate - /// - fn fib(mut n: u32) -> u32 { - let mut a: u32 = 0; - let mut b: u32 = 1; - while n != 0 { - n = n - 1; - let temp = b; - b = a + b; - a = temp; - }; - a - } - - /// Pair type alias for a tuple of two u32 values - type Pair = (u32, u32); - - /// Color enum with Red, Green, and Blue variants - enum Color { - /// Red color - Red: (), - /// Green color - Green: (), - /// Blue color - Blue: (), - } - - /// Shape trait for objects that have an area - trait Shape { - /// Constant for the shape type - const SHAPE_CONST: felt252; - - /// Type alias for a pair of shapes - type ShapePair; - - /// Calculate the area of the shape - fn area(self: T) -> u32; - } - - /// Circle struct with radius field - #[derive(Drop, Serde, PartialEq)] - struct Circle { - /// Radius of the circle - radius: u32, - } - - /// Implementation of the Shape trait for Circle - impl CircleShape of Shape { - /// Type alias for a pair of circles - type ShapePair = (Circle, Circle); - - /// Shape constant - const SHAPE_CONST: felt252 = 'xyz'; - - /// Implementation of the area method for Circle - fn area(self: Circle) -> u32 { - 3 * self.radius * self.radius - } - } - - /// Tests module - mod tests { - /// Imported fib function from the parent module - use super::fib as fib_function; - - /// Really - #[test] - /// works. - fn it_works() { - assert(fib_function(16) == 987, 'it works!'); - } - } - "# -}; - -#[test] -fn json_output() { - let t = TempDir::new().unwrap(); - ProjectBuilder::start() - .name("hello_world") - .lib_cairo(CODE) - .build(&t); - - Scarb::quick_snapbox() - .arg("doc") - .args(["--output-format", "json"]) - .current_dir(&t) - .assert() - .success(); - - let serialized_crates = fs::read_to_string(t.path().join("target/doc/output.json")) - .expect("Failed to read from file"); - let expected = expect_file!["./data/json_output_test_data.json"]; - expected.assert_eq(&serialized_crates); -} - -#[test] -fn markdown_output() { - let t = TempDir::new().unwrap(); - ProjectBuilder::start() - .name("hello_world") - .lib_cairo(CODE) - .build(&t); - - Scarb::quick_snapbox() - .arg("doc") - .args(["--output-format", "markdown"]) - .current_dir(&t) - .assert() - .success(); - - for (dir_entry_1, dir_entry_2) in zip( - WalkDir::new("tests/data/hello_world").sort_by_file_name(), - WalkDir::new(t.path().join("target/doc/hello_world")).sort_by_file_name(), - ) { - let dir_entry_1 = dir_entry_1.unwrap(); - let dir_entry_2 = dir_entry_2.unwrap(); - - if dir_entry_1.file_type().is_file() { - assert!(dir_entry_2.file_type().is_file()); - - let content = fs::read_to_string(dir_entry_2.path()).unwrap(); - - let expect_file = expect_file![fsx::canonicalize(dir_entry_1.path()).unwrap()]; - expect_file.assert_eq(&content); - } - } -}