Skip to content

Commit

Permalink
feat: Add implementations to forc-doc (#6017)
Browse files Browse the repository at this point in the history 
## Description

Closes #5957

Also tweaked the CSS to make:
- the subheaders inside of implementations smaller than the impl header
- the colors a little less stark
- the impl toggle blocks open by default (same as crates.io)

Discovered two issues, relating to enums and the sidebar, which I'll
solve separately: #6018


![image](https://github.com/FuelLabs/sway/assets/47993817/907f59c9-8555-4f0f-9ab2-353d4c17fa12)

## Checklist

- [ ] I have linked to any relevant issues.
- [ ] I have commented my code, particularly in hard-to-understand
areas.
- [ ] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [ ] If my change requires substantial documentation changes, I have
[requested support from the DevRel
team](https://github.com/FuelLabs/devrel-requests/issues/new/choose)
- [ ] I have added tests that prove my fix is effective or that my
feature works.
- [ ] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [ ] I have done my best to ensure that my PR adheres to [the Fuel Labs
Code Review
Standards](https://github.com/FuelLabs/rfcs/blob/master/text/code-standards/external-contributors.md).
- [ ] I have requested a review from the relevant team or maintainers.

---------

Co-authored-by: Joshua Batty <joshpbatty@gmail.com>
  • Loading branch information
@sdankel @JoshuaBatty
sdankel and JoshuaBatty authored May 15, 2024
1 parent 79b5651 commit d4f0c12
Show file tree
Hide file tree
Showing 6 changed files with 84 additions and 45 deletions.
14 changes: 7 additions & 7 deletions forc-plugins/forc-doc/src/doc/descriptor.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ impl Descriptor {
attrs_opt: attrs_opt.clone(),
item_context: ItemContext {
context_opt: context,
impl_traits: None,
..Default::default()
},
},
raw_attributes: attrs_opt,
Expand Down Expand Up @@ -110,7 +110,7 @@ impl Descriptor {
attrs_opt: attrs_opt.clone(),
item_context: ItemContext {
context_opt: context,
impl_traits: None,
..Default::default()
},
},
raw_attributes: attrs_opt,
Expand Down Expand Up @@ -158,7 +158,7 @@ impl Descriptor {
attrs_opt: attrs_opt.clone(),
item_context: ItemContext {
context_opt: context,
impl_traits: None,
..Default::default()
},
},
raw_attributes: attrs_opt,
Expand Down Expand Up @@ -200,7 +200,7 @@ impl Descriptor {
attrs_opt: attrs_opt.clone(),
item_context: ItemContext {
context_opt: context,
impl_traits: None,
..Default::default()
},
},
raw_attributes: attrs_opt,
Expand Down Expand Up @@ -235,7 +235,7 @@ impl Descriptor {
attrs_opt: attrs_opt.clone(),
item_context: ItemContext {
context_opt: context,
impl_traits: None,
..Default::default()
},
},
raw_attributes: attrs_opt,
Expand Down Expand Up @@ -267,7 +267,7 @@ impl Descriptor {
attrs_opt: attrs_opt.clone(),
item_context: ItemContext {
context_opt: None,
impl_traits: None,
..Default::default()
},
},
raw_attributes: attrs_opt,
Expand Down Expand Up @@ -300,7 +300,7 @@ impl Descriptor {
attrs_opt: attrs_opt.clone(),
item_context: ItemContext {
context_opt: None,
impl_traits: None,
..Default::default()
},
},
raw_attributes: attrs_opt,
Expand Down
39 changes: 27 additions & 12 deletions forc-plugins/forc-doc/src/doc/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,16 +76,17 @@ impl Documentation {
// currently this compares the spans as str, but this needs to change
// to compare the actual types
for doc in docs.iter_mut() {
let mut impl_vec: Vec<DocImplTrait> = Vec::new();
let mut impl_trait_vec: Vec<DocImplTrait> = Vec::new();
let mut inherent_impl_vec: Vec<DocImplTrait> = Vec::new();

match doc.item_body.ty_decl {
TyDecl::StructDecl(ref decl) => {
for (impl_trait, module_info) in impl_traits.iter_mut() {
let struct_decl = engines.de().get_struct(&decl.decl_id);
if struct_decl.name().as_str() == impl_trait.implementing_for.span.as_str()
&& struct_decl.name().as_str()
!= impl_trait.trait_name.suffix.span().as_str()
{
let struct_name = struct_decl.name().as_str();

// Check if this implementation is for this struct.
if struct_name == impl_trait.implementing_for.span.as_str() {
let module_info_override = if let Some(decl_module_info) =
trait_decls.get(&impl_trait.trait_name.suffix)
{
Expand All @@ -97,19 +98,33 @@ impl Documentation {
None
};

impl_vec.push(DocImplTrait {
impl_for_module: module_info.clone(),
impl_trait: impl_trait.clone(),
module_info_override,
});
if struct_name == impl_trait.trait_name.suffix.span().as_str() {
// If the trait name is the same as the struct name, it's an inherent implementation.
inherent_impl_vec.push(DocImplTrait {
impl_for_module: module_info.clone(),
impl_trait: impl_trait.clone(),
module_info_override: None,
});
} else {
// Otherwise, it's an implementation for a trait.
impl_trait_vec.push(DocImplTrait {
impl_for_module: module_info.clone(),
impl_trait: impl_trait.clone(),
module_info_override,
});
}
}
}
}
_ => continue,
}

if !impl_vec.is_empty() {
doc.item_body.item_context.impl_traits = Some(impl_vec);
if !impl_trait_vec.is_empty() {
doc.item_body.item_context.impl_traits = Some(impl_trait_vec.clone());
}

if !inherent_impl_vec.is_empty() {
doc.item_body.item_context.inherent_impls = Some(inherent_impl_vec);
}
}

Expand Down
54 changes: 41 additions & 13 deletions forc-plugins/forc-doc/src/render/item/context.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -264,22 +264,25 @@ impl Renderable for Context {
})
}
}

#[derive(Debug, Clone)]
pub struct DocImplTrait {
pub impl_for_module: ModuleInfo,
pub impl_trait: TyImplTrait,
pub module_info_override: Option<Vec<String>>,
}
#[derive(Clone, Debug)]

#[derive(Clone, Debug, Default)]
/// The context section of an item that appears in the page [ItemBody].
pub struct ItemContext {
/// [Context] can be fields on a struct, variants of an enum, etc.
pub context_opt: Option<Context>,
// The implementations for this type.
pub inherent_impls: Option<Vec<DocImplTrait>>,
/// The traits implemented for this type.
pub impl_traits: Option<Vec<DocImplTrait>>,
// TODO: All other Implementation types, eg
// implementations on foreign types, method implementations, etc.
}

impl ItemContext {
pub fn to_doclinks(&self) -> DocLinks {
let mut links: BTreeMap<BlockTitle, Vec<DocLink>> = BTreeMap::new();
Expand Down Expand Up @@ -379,26 +382,48 @@ impl Renderable for ItemContext {

let impl_traits = match self.impl_traits {
Some(impl_traits) => {
let mut impl_vec: Vec<_> = Vec::with_capacity(impl_traits.len());
let mut impl_trait_vec: Vec<_> = Vec::with_capacity(impl_traits.len());
for impl_trait in impl_traits {
impl_vec.push(impl_trait.render(render_plan.clone())?);
impl_trait_vec.push(impl_trait.render(render_plan.clone())?);
}
Some(impl_vec)
impl_trait_vec
}
None => None,
None => vec![],
};

let inherent_impls = match self.inherent_impls {
Some(inherent_impls) => {
let mut inherent_impl_vec: Vec<_> = Vec::with_capacity(inherent_impls.len());
for inherent_impl in inherent_impls {
inherent_impl_vec.push(inherent_impl.render(render_plan.clone())?);
}
inherent_impl_vec
}
None => vec![],
};

Ok(box_html! {
@ if let Some(context) = context_opt {
: Raw(context);
}
@ if impl_traits.is_some() {
@ if !inherent_impls.is_empty() {
h2(id="inherent-implementations", class="small-section-header") {
: "Implementations";
a(href=format!("{IDENTITY}inherent-implementations"), class="anchor");
}
div(id="inherent-implementations-list") {
@ for inherent_impl in inherent_impls {
: inherent_impl;
}
}
}
@ if !impl_traits.is_empty() {
h2(id="trait-implementations", class="small-section-header") {
: "Trait Implementations";
a(href=format!("{IDENTITY}trait-implementations"), class="anchor");
}
div(id="trait-implementations-list") {
@ for impl_trait in impl_traits.unwrap() {
@ for impl_trait in impl_traits {
: impl_trait;
}
}
Expand All @@ -414,6 +439,7 @@ impl Renderable for DocImplTrait {
implementing_for,
..
} = self.impl_trait;
let is_inherent = trait_name.suffix.as_str() == implementing_for.span.as_str();
let impl_for_module = self.impl_for_module;
let no_deps = render_plan.no_deps;
let is_external_item = if let Some(project_root) = trait_name.prefixes.first() {
Expand Down Expand Up @@ -453,8 +479,10 @@ impl Renderable for DocImplTrait {
: trait_name.suffix.as_str();
}
}
: " for ";
: implementing_for.span.as_str();
@ if !is_inherent {
: " for ";
: implementing_for.span.as_str();
}
}
}
}
Expand All @@ -463,7 +491,7 @@ impl Renderable for DocImplTrait {
Ok(box_html! {
// check if the implementation has methods
@ if !rendered_items.is_empty() {
details(class="swaydoc-toggle implementors-toggle") {
details(class="swaydoc-toggle implementors-toggle", open) {
summary {
: Raw(impl_for);
}
Expand Down Expand Up @@ -582,7 +610,7 @@ impl Renderable for TyTraitItem {
summary {
: Raw(impl_list);
}
div(class="doc-block") {
div(class="docblock") {
: Raw(attributes);
}
}
Expand Down
4 changes: 2 additions & 2 deletions forc-plugins/forc-doc/src/static.files/ayu.css
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
:root {
--main-background-color: #0f1419;
--main-background-color: #262e37;
--main-color: #c5c5c5;
--settings-input-color: #ffb454;
--sidebar-background-color: #14191f;
--sidebar-background-color: #161f25;
--sidebar-background-color-hover: rgba(70, 70, 70, 0.33);
--code-block-background-color: #191f26;
--scrollbar-track-background-color: transparent;
Expand Down
10 changes: 3 additions & 7 deletions forc-plugins/forc-doc/src/static.files/swaydoc.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -152,7 +152,7 @@ h2,
border-bottom: 1px solid var(--headings-border-bottom-color);
}
h3.code-header {
font-size: 1em;
font-size: 1.125rem;
font-weight: 600;
}
h4.code-header {
Expand Down Expand Up @@ -604,18 +604,14 @@ h2.location a {
.top-doc .docblock h6 {
font-size: 1rem;
}
.docblock h5 {
font-size: 1rem;
}
.docblock h6 {
font-size: 0.875rem;
}
.docblock h1,
.docblock h2,
.docblock h3,
.docblock h4,
.docblock h5,
.docblock h6 {
font-size: 1.125rem;
color: var(--main-color);
border-bottom-color: var(--headings-border-bottom-color);
}
.docblock {
Expand Down
Loading

0 comments on commit d4f0c12

Please sign in to comment.