Skip to content

Commit

Permalink
Improve forc doc navigation interface (FuelLabs#4212)
Browse files Browse the repository at this point in the history
## Description

Changes the path to the root when clicking the Sway logo. Adds some nice
CSS for the button that navigates to the `all doc`, and adds links to
each parent module in a `CallPath`.

[Screencast from 2023-03-07
17-20-16.webm](https://user-images.githubusercontent.com/57543709/223628980-855d29dd-029f-440e-89e2-96f8484741a9.webm)



## Checklist

- [x] I have linked to any relevant issues. 
    Closes FuelLabs#3996 
    Closes FuelLabs#4195 
    Closes FuelLabs#4197 
    Closes FuelLabs#4196 
- [x] I have commented my code, particularly in hard-to-understand
areas.
- [x] I have updated the documentation where relevant (API docs, the
reference, and the Sway book).
- [x] I have added tests that prove my fix is effective or that my
feature works.
- [x] I have added (or requested a maintainer to add) the necessary
`Breaking*` or `New Feature` labels where relevant.
- [x] 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).
- [x] I have requested a review from the relevant team or maintainers.
  • Loading branch information
eureka-cpu authored Mar 9, 2023
1 parent dd01aef commit eac5a0a
Show file tree
Hide file tree
Showing 5 changed files with 266 additions and 128 deletions.
13 changes: 9 additions & 4 deletions forc-plugins/forc-doc/src/assets/ayu.css
Original file line number Diff line number Diff line change
Expand Up @@ -169,9 +169,6 @@ pre,
.content a.macro {
color: #a37acc;
}
.sidebar a {
color: #53b1db;
}
.sidebar a.current.type {
color: #53b1db;
}
Expand All @@ -192,7 +189,7 @@ nav.main .separator {
border: 1px solid #5c6773;
}
a {
color: #39afd7;
color: #c5c5c5;
}
.sidebar h2 a,
.sidebar h3 a {
Expand Down Expand Up @@ -487,3 +484,11 @@ details.dir-entry summary:focus {
.toggle-line:hover .toggle-line-inner {
background: #c5c5c5;
}
.sidebar .location {
border-color: #000;
background-color: #0f1419;
color: #fff;
}
#all-types {
background-color: #14191f;
}
32 changes: 25 additions & 7 deletions forc-plugins/forc-doc/src/assets/swaydoc.css
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@ html {
}
}
body {
font: 1rem/1.5 "Source Serif 4", NanumBarunGothic, serif;
font: 16px/1.4 "Source Serif 4", NanumBarunGothic, serif;
margin: 0;
position: relative;
overflow-wrap: break-word;
Expand Down Expand Up @@ -249,7 +249,7 @@ ol ol {
margin-bottom: 0.625em;
}
p {
margin: 0 0 0.75em 0;
margin: 0 0 .6em 0;
}
summary {
outline: none;
Expand Down Expand Up @@ -363,20 +363,25 @@ nav.sub {
}
.sidebar {
font-size: 0.875rem;
width: 250px;
width: 200px;
min-width: 200px;
overflow-y: scroll;
position: sticky;
height: 100vh;
top: 0;
left: 0;
}
.sidebar-elems,
.sidebar > .location {
padding-left: 24px;
}
.sidebar .location {
overflow-wrap: anywhere;
border: 1px solid;
font-size: 17px;
margin: 30px 10px 20px 10px;
text-align: center;
word-wrap: break-word;
font-weight: inherit;
padding: 0;
}
.swaydoc.source .sidebar {
width: 50px;
Expand Down Expand Up @@ -413,7 +418,17 @@ nav.sub {
visibility: visible;
}
#all-types {
margin-top: 1em;
text-align: center;
border: 1px solid;
margin: 0 10px;
margin-bottom: 10px;
display: block;
border-radius: 7px;
}
a#all-types:hover,
a#all-types:active {
background-color: var(--sidebar-background-color-hover);
color: #c5c5c5;
}
* {
scrollbar-width: initial;
Expand Down Expand Up @@ -475,7 +490,7 @@ nav.sub {
h2.location a {
display: block;
padding: 0.25rem;
margin-left: -0.25rem;
margin-left: 2em;
text-overflow: ellipsis;
overflow: hidden;
}
Expand Down Expand Up @@ -1994,3 +2009,6 @@ details.swaydoc-toggle[open] > summary.hideme::after {
.example-links ul {
margin-bottom: 0;
}
#all-types>p {
margin: 5px 0;
}
28 changes: 26 additions & 2 deletions forc-plugins/forc-doc/src/doc.rs
Original file line number Diff line number Diff line change
@@ -1,10 +1,13 @@
use crate::{
descriptor::Descriptor,
render::{split_at_markdown_header, DocLink, DocStrings, ItemBody, ItemHeader, Renderable},
render::{
split_at_markdown_header, DocLink, DocStrings, ItemBody, ItemHeader, Renderable,
INDEX_FILENAME,
},
RenderPlan,
};
use anyhow::Result;
use horrorshow::{box_html, RenderBox};
use horrorshow::{box_html, RenderBox, Template};
use std::{fmt::Write, option::Option, path::PathBuf};
use sway_core::{
decl_engine::DeclEngine,
Expand Down Expand Up @@ -215,6 +218,27 @@ impl ModuleInfo {
}
iter.map(|s| s.as_str()).collect::<Vec<&str>>().join("::")
}
/// Renders the [ModuleInfo] into a [CallPath] with anchors. We return this as a `Result<Vec<String>>`
/// since the `box_html!` macro returns a closure and no two closures are considered the same type.
pub(crate) fn get_anchors(&self) -> Result<Vec<String>> {
let mut count = self.depth();
let mut rendered_module_anchors = Vec::with_capacity(self.depth());
for prefix in self.module_prefixes.iter() {
let mut href = (1..count).map(|_| "../").collect::<String>();
href.push_str(INDEX_FILENAME);
rendered_module_anchors.push(
box_html! {
a(class="mod", href=href) {
: prefix;
}
span: "::";
}
.into_string()?,
);
count -= 1;
}
Ok(rendered_module_anchors)
}
/// Creates a String version of the path to an item,
/// used in navigation between pages. The location given is the break point.
///
Expand Down
2 changes: 1 addition & 1 deletion forc-plugins/forc-doc/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ pub fn main() -> Result<()> {
.project
.forc_version
.as_ref()
.map(|ver| format!("{}.{}.{}", ver.major, ver.minor, ver.patch));
.map(|ver| format!("Forc v{}.{}.{}", ver.major, ver.minor, ver.patch));
let rendered_docs = RenderedDocumentation::from(
raw_docs,
RenderPlan::new(
Expand Down
Loading

0 comments on commit eac5a0a

Please sign in to comment.