Skip to content

Commit

Permalink
Merge branch 'main' into scarb-new-interactive
Browse files Browse the repository at this point in the history
  • Loading branch information
@ksew1
ksew1 authored Jul 23, 2024
2 parents b540c7f + a142df1 commit 655adbf
Show file tree
Hide file tree
Showing 22 changed files with 388 additions and 225 deletions.
108 changes: 54 additions & 54 deletions Cargo.lock
View file

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ inquire = "0.7.5"
io_tee = "0.1"
itertools = "0.12"
libc = "0.2"
libloading = "0.8.4"
libloading = "0.8.5"
linkme = "0.3"
log = "0.4"
ntest = "0.9"
Expand Down
44 changes: 24 additions & 20 deletions extensions/scarb-doc/src/docs_generation.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -106,15 +106,19 @@ impl TopLevelDocItem for TypeAlias {}

// Wrapper trait over a documentable item to hide implementation details of the item type.
trait DocItem {
const HEADER: &'static str;

fn name(&self) -> &str;
fn doc(&self) -> &Option<String>;
fn signature(&self) -> &Option<String>;
fn full_path(&self) -> &str;
}

macro_rules! impl_doc_item {
($t:ty) => {
($t:ty, $name:expr) => {
impl DocItem for $t {
const HEADER: &'static str = $name;

fn name(&self) -> &str {
&self.item_data.name
}
Expand All @@ -134,22 +138,22 @@ macro_rules! impl_doc_item {
};
}

impl_doc_item!(Constant);
impl_doc_item!(Enum);
impl_doc_item!(ExternFunction);
impl_doc_item!(ExternType);
impl_doc_item!(FreeFunction);
impl_doc_item!(Impl);
impl_doc_item!(ImplAlias);
impl_doc_item!(ImplConstant);
impl_doc_item!(ImplFunction);
impl_doc_item!(ImplType);
impl_doc_item!(Member);
impl_doc_item!(Module);
impl_doc_item!(Struct);
impl_doc_item!(Trait);
impl_doc_item!(TraitConstant);
impl_doc_item!(TraitType);
impl_doc_item!(TraitFunction);
impl_doc_item!(TypeAlias);
impl_doc_item!(Variant);
impl_doc_item!(Constant, "Constants");
impl_doc_item!(Enum, "Enums");
impl_doc_item!(ExternFunction, "Extern functions");
impl_doc_item!(ExternType, "Extern types");
impl_doc_item!(FreeFunction, "Free functions");
impl_doc_item!(Impl, "Impls");
impl_doc_item!(ImplAlias, "Impl aliases");
impl_doc_item!(ImplConstant, "Impl constants");
impl_doc_item!(ImplFunction, "Impl functions");
impl_doc_item!(ImplType, "Impl types");
impl_doc_item!(Member, "Members");
impl_doc_item!(Module, "Modules");
impl_doc_item!(Struct, "Structs");
impl_doc_item!(Trait, "Traits");
impl_doc_item!(TraitConstant, "Trait constants");
impl_doc_item!(TraitType, "Trait types");
impl_doc_item!(TraitFunction, "Trait functions");
impl_doc_item!(TypeAlias, "Type aliases");
impl_doc_item!(Variant, "Variants");
142 changes: 98 additions & 44 deletions extensions/scarb-doc/src/docs_generation/markdown.rs
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,18 @@
use anyhow::{Context, Result};
use camino::Utf8Path;
use itertools::chain;
use itertools::{chain, Itertools};
use std::fs;

use crate::docs_generation::markdown::book_toml::generate_book_toml_content;
use crate::docs_generation::markdown::summary::generate_summary_file_content;
use crate::docs_generation::markdown::traits::TopLevelMarkdownDocItem;
use crate::docs_generation::markdown::traits::{
generate_markdown_list_for_top_level_subitems, TopLevelMarkdownDocItem,
};
use crate::docs_generation::{collect_all_top_level_items, TopLevelItems};
use crate::types::{
Constant, Enum, ExternFunction, ExternType, FreeFunction, Impl, ImplAlias, Module, Struct,
Trait, TypeAlias,
};
use crate::PackageInformation;

mod book_toml;
Expand All @@ -18,49 +24,102 @@ const SOURCE_DIRECTORY: &str = "src";
const BOOK_TOML_FILENAME: &str = "book.toml";
const SUMMARY_FILENAME: &str = "SUMMARY.md";

pub struct MarkdownContent<'a> {
type Filename = String;

pub struct MarkdownContent {
book_toml: String,
summary: String,
top_level_docs: Vec<(&'a dyn TopLevelMarkdownDocItem, String)>,
doc_files: Vec<(Filename, String)>,
}

impl<'a> MarkdownContent<'a> {
pub fn from_crate(package_information: &'a PackageInformation) -> Self {
impl MarkdownContent {
pub fn from_crate(package_information: &PackageInformation) -> Self {
let top_level_items = collect_all_top_level_items(&package_information.crate_);

let summary_file_content = generate_summary_file_content(&top_level_items);
let TopLevelItems {
ref modules,
ref constants,
ref free_functions,
ref structs,
ref enums,
ref type_aliases,
ref impl_aliases,
ref traits,
ref impls,
ref extern_types,
ref extern_functions,
modules,
constants,
free_functions,
structs,
enums,
type_aliases,
impl_aliases,
traits,
impls,
extern_types,
extern_functions,
} = top_level_items;

let top_level_docs = chain!(
generate_top_level_docs_contents(modules),
generate_top_level_docs_contents(constants),
generate_top_level_docs_contents(free_functions),
generate_top_level_docs_contents(structs),
generate_top_level_docs_contents(enums),
generate_top_level_docs_contents(type_aliases),
generate_top_level_docs_contents(impl_aliases),
generate_top_level_docs_contents(traits),
generate_top_level_docs_contents(impls),
generate_top_level_docs_contents(extern_types),
generate_top_level_docs_contents(extern_functions),
let docs_for_top_level_items = chain!(
generate_top_level_docs_contents(&modules),
generate_top_level_docs_contents(&constants),
generate_top_level_docs_contents(&free_functions),
generate_top_level_docs_contents(&structs),
generate_top_level_docs_contents(&enums),
generate_top_level_docs_contents(&type_aliases),
generate_top_level_docs_contents(&impl_aliases),
generate_top_level_docs_contents(&traits),
generate_top_level_docs_contents(&impls),
generate_top_level_docs_contents(&extern_types),
generate_top_level_docs_contents(&extern_functions),
)
.collect();
.collect_vec();

let summaries_for_top_level_items = vec![
(
Module::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&modules, BASE_HEADER_LEVEL),
),
(
Constant::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&constants, BASE_HEADER_LEVEL),
),
(
FreeFunction::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&free_functions, BASE_HEADER_LEVEL),
),
(
Struct::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&structs, BASE_HEADER_LEVEL),
),
(
Enum::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&enums, BASE_HEADER_LEVEL),
),
(
TypeAlias::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&type_aliases, BASE_HEADER_LEVEL),
),
(
ImplAlias::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&impl_aliases, BASE_HEADER_LEVEL),
),
(
Trait::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&traits, BASE_HEADER_LEVEL),
),
(
Impl::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&impls, BASE_HEADER_LEVEL),
),
(
ExternType::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&extern_types, BASE_HEADER_LEVEL),
),
(
ExternFunction::ITEMS_SUMMARY_FILENAME.to_string(),
generate_markdown_list_for_top_level_subitems(&extern_functions, BASE_HEADER_LEVEL),
),
]
.into_iter()
.filter(|(_filename, content)| !content.is_empty())
.collect_vec();

Self {
book_toml: generate_book_toml_content(&package_information.metadata),
summary: generate_summary_file_content(&top_level_items),
top_level_docs,
summary: summary_file_content,
doc_files: chain!(docs_for_top_level_items, summaries_for_top_level_items).collect(),
}
}

Expand All @@ -75,25 +134,20 @@ impl<'a> MarkdownContent<'a> {
fs::write(source_directory_path.join(SUMMARY_FILENAME), self.summary)
.context("failed to write summary content to a file")?;

for (item, file_content) in self.top_level_docs {
fs::write(source_directory_path.join(item.filename()), file_content)
.context("failed to write content to a file")?;
for (filename, file_content) in self.doc_files {
fs::write(source_directory_path.join(filename), file_content)
.context("failed to write content to a doc file")?;
}

Ok(())
}
}

fn generate_top_level_docs_contents<'a>(
items: &[&'a impl TopLevelMarkdownDocItem],
) -> Vec<(&'a dyn TopLevelMarkdownDocItem, String)> {
fn generate_top_level_docs_contents(
items: &[&impl TopLevelMarkdownDocItem],
) -> Vec<(Filename, String)> {
items
.iter()
.map(|item| {
(
*item as &dyn TopLevelMarkdownDocItem,
item.generate_markdown(BASE_HEADER_LEVEL),
)
})
.map(|item| (item.filename(), item.generate_markdown(BASE_HEADER_LEVEL)))
.collect()
}
70 changes: 35 additions & 35 deletions extensions/scarb-doc/src/docs_generation/markdown/summary.rs
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
use crate::docs_generation::markdown::traits::generate_markdown_list_for_top_level_subitems;
use std::fmt::Write;

use crate::docs_generation::markdown::traits::TopLevelMarkdownDocItem;
use crate::docs_generation::markdown::BASE_HEADER_LEVEL;
use crate::docs_generation::TopLevelItems;

Expand All @@ -21,40 +23,38 @@ pub fn generate_summary_file_content(top_level_items: &TopLevelItems) -> String
extern_functions,
} = top_level_items;

markdown +=
&generate_markdown_list_for_top_level_subitems(modules, "Modules", BASE_HEADER_LEVEL);
markdown +=
&generate_markdown_list_for_top_level_subitems(constants, "Constants", BASE_HEADER_LEVEL);
markdown += &generate_markdown_list_for_top_level_subitems(
free_functions,
"Free functions",
BASE_HEADER_LEVEL,
);
markdown +=
&generate_markdown_list_for_top_level_subitems(structs, "Structs", BASE_HEADER_LEVEL);
markdown += &generate_markdown_list_for_top_level_subitems(enums, "Enums", BASE_HEADER_LEVEL);
markdown += &generate_markdown_list_for_top_level_subitems(
type_aliases,
"Type Aliases",
BASE_HEADER_LEVEL,
);
markdown += &generate_markdown_list_for_top_level_subitems(
impl_aliases,
"Impl Aliases",
BASE_HEADER_LEVEL,
);
markdown += &generate_markdown_list_for_top_level_subitems(traits, "Traits", BASE_HEADER_LEVEL);
markdown += &generate_markdown_list_for_top_level_subitems(impls, "Impls", BASE_HEADER_LEVEL);
markdown += &generate_markdown_list_for_top_level_subitems(
extern_types,
"Extern types",
BASE_HEADER_LEVEL,
);
markdown += &generate_markdown_list_for_top_level_subitems(
extern_functions,
"Extern functions",
BASE_HEADER_LEVEL,
);
markdown += &generate_markdown_list_summary_for_top_level_subitems(modules);
markdown += &generate_markdown_list_summary_for_top_level_subitems(constants);
markdown += &generate_markdown_list_summary_for_top_level_subitems(free_functions);
markdown += &generate_markdown_list_summary_for_top_level_subitems(structs);
markdown += &generate_markdown_list_summary_for_top_level_subitems(enums);
markdown += &generate_markdown_list_summary_for_top_level_subitems(type_aliases);
markdown += &generate_markdown_list_summary_for_top_level_subitems(impl_aliases);
markdown += &generate_markdown_list_summary_for_top_level_subitems(traits);
markdown += &generate_markdown_list_summary_for_top_level_subitems(impls);
markdown += &generate_markdown_list_summary_for_top_level_subitems(extern_types);
markdown += &generate_markdown_list_summary_for_top_level_subitems(extern_functions);

markdown
}

fn generate_markdown_list_summary_for_top_level_subitems<T: TopLevelMarkdownDocItem>(
subitems: &[&T],
) -> String {
let mut markdown = String::new();

if !subitems.is_empty() {
writeln!(
&mut markdown,
"- [{}](./{})\n",
T::HEADER,
T::ITEMS_SUMMARY_FILENAME
)
.unwrap();
for item in subitems {
writeln!(&mut markdown, " {}", item.generate_markdown_list_item()).unwrap();
}
}

markdown
}
Loading

0 comments on commit 655adbf

Please sign in to comment.