forked from FuelLabs/sway
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore(forc-doc): Reorganizes the file tree (FuelLabs#4382)
## Description Just a clean up PR to make finding & understanding things much easier. ## Checklist - [x] I have linked to any relevant issues. FuelLabs#3656 FuelLabs#3659 - [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
1 parent
d6238ae
commit 085175a
Showing
20 changed files
with
1,838 additions
and
1,709 deletions.
There are no files selected for viewing
7 changes: 5 additions & 2 deletions
7
forc-plugins/forc-doc/src/descriptor.rs → forc-plugins/forc-doc/src/doc/descriptor.rs
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,137 @@ | ||
| use crate::{ | ||
| doc::{descriptor::Descriptor, module::ModuleInfo}, | ||
| render::{item::components::*, link::DocLink, util::format::docstring::*}, | ||
| }; | ||
| use anyhow::Result; | ||
| use std::option::Option; | ||
| use sway_core::{ | ||
| decl_engine::DeclEngine, | ||
| language::ty::{TyAstNodeContent, TyProgram, TySubmodule}, | ||
| }; | ||
|
|
||
| mod descriptor; | ||
| pub mod module; | ||
|
|
||
| pub(crate) type Documentation = Vec<Document>; | ||
| /// A finalized Document ready to be rendered. We want to retain all | ||
| /// information including spans, fields on structs, variants on enums etc. | ||
| #[derive(Clone, Debug)] | ||
| pub(crate) struct Document { | ||
| pub(crate) module_info: ModuleInfo, | ||
| pub(crate) item_header: ItemHeader, | ||
| pub(crate) item_body: ItemBody, | ||
| pub(crate) raw_attributes: Option<String>, | ||
| } | ||
| impl Document { | ||
| /// Creates an HTML file name from the [Document]. | ||
| pub(crate) fn html_filename(&self) -> String { | ||
| use sway_core::language::ty::TyDecl::StorageDecl; | ||
| let name = match &self.item_body.ty_decl { | ||
| StorageDecl { .. } => None, | ||
| _ => Some(self.item_header.item_name.as_str()), | ||
| }; | ||
|
|
||
| Document::create_html_filename(self.item_body.ty_decl.doc_name(), name) | ||
| } | ||
| fn create_html_filename(ty: &str, name: Option<&str>) -> String { | ||
| match name { | ||
| Some(name) => format!("{ty}.{name}.html"), | ||
| None => { | ||
| format!("{ty}.html") // storage does not have an Ident | ||
| } | ||
| } | ||
| } | ||
| /// Generate link info used in navigation between docs. | ||
| pub(crate) fn link(&self) -> DocLink { | ||
| DocLink { | ||
| name: self.item_header.item_name.as_str().to_owned(), | ||
| module_info: self.module_info.clone(), | ||
| html_filename: self.html_filename(), | ||
| preview_opt: self.preview_opt(), | ||
| } | ||
| } | ||
| fn preview_opt(&self) -> Option<String> { | ||
| create_preview(self.raw_attributes.clone()) | ||
| } | ||
| /// Gather [Documentation] from the [TyProgram]. | ||
| pub(crate) fn from_ty_program( | ||
| decl_engine: &DeclEngine, | ||
| project_name: &str, | ||
| typed_program: &TyProgram, | ||
| no_deps: bool, | ||
| document_private_items: bool, | ||
| ) -> Result<Documentation> { | ||
| // the first module prefix will always be the project name | ||
| let mut docs: Documentation = Default::default(); | ||
| for ast_node in &typed_program.root.all_nodes { | ||
| if let TyAstNodeContent::Declaration(ref decl) = ast_node.content { | ||
| let desc = Descriptor::from_typed_decl( | ||
| decl_engine, | ||
| decl, | ||
| ModuleInfo::from_ty_module(vec![project_name.to_owned()], None), | ||
| document_private_items, | ||
| )?; | ||
|
|
||
| if let Descriptor::Documentable(doc) = desc { | ||
| docs.push(doc) | ||
| } | ||
| } | ||
| } | ||
|
|
||
| if !no_deps && !typed_program.root.submodules.is_empty() { | ||
| // this is the same process as before but for dependencies | ||
| for (_, ref typed_submodule) in &typed_program.root.submodules { | ||
| let attributes = (!typed_submodule.module.attributes.is_empty()) | ||
| .then(|| typed_submodule.module.attributes.to_html_string()); | ||
| let module_prefix = | ||
| ModuleInfo::from_ty_module(vec![project_name.to_owned()], attributes); | ||
| Document::from_ty_submodule( | ||
| decl_engine, | ||
| typed_submodule, | ||
| &mut docs, | ||
| &module_prefix, | ||
| document_private_items, | ||
| )?; | ||
| } | ||
| } | ||
|
|
||
| Ok(docs) | ||
| } | ||
| fn from_ty_submodule( | ||
| decl_engine: &DeclEngine, | ||
| typed_submodule: &TySubmodule, | ||
| docs: &mut Documentation, | ||
| module_prefix: &ModuleInfo, | ||
| document_private_items: bool, | ||
| ) -> Result<()> { | ||
| let mut new_submodule_prefix = module_prefix.to_owned(); | ||
| new_submodule_prefix | ||
| .module_prefixes | ||
| .push(typed_submodule.mod_name_span.as_str().to_owned()); | ||
| for ast_node in &typed_submodule.module.all_nodes { | ||
| if let TyAstNodeContent::Declaration(ref decl) = ast_node.content { | ||
| let desc = Descriptor::from_typed_decl( | ||
| decl_engine, | ||
| decl, | ||
| new_submodule_prefix.clone(), | ||
| document_private_items, | ||
| )?; | ||
|
|
||
| if let Descriptor::Documentable(doc) = desc { | ||
| docs.push(doc) | ||
| } | ||
| } | ||
| } | ||
| for (_, submodule) in &typed_submodule.module.submodules { | ||
| Document::from_ty_submodule( | ||
| decl_engine, | ||
| submodule, | ||
| docs, | ||
| &new_submodule_prefix, | ||
| document_private_items, | ||
| )?; | ||
| } | ||
|
|
||
| Ok(()) | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.