Add workspace support to forc-doc

[JoshuaBatty]

Description

Adds workspace-level documentation support to forc doc. When invoked from the root of a workspace, it now generates a landing page that lists all member libraries along with their descriptions extracted directly from each Forc.toml.

Below is an example of the landing page generated when running forc doc at the root of the sway-libs workspace.

Closes #4103

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
• 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.
• I have requested a review from the relevant team or maintainers.

[codspeed-hq]

CodSpeed Performance Report

Merging #7268 will not alter performance

_{Comparing josh/forc_doc_workspace (a57b398) with master (73fb343)}

Summary

✅ 25 untouched benchmarks

[zees-dev]

Looking good; however i think we can do without the pkg_manifest and is_workspace attributes on the DocContext struct; example diff provided:

patch

diff --git a/forc-plugins/forc-doc/src/lib.rs b/forc-plugins/forc-doc/src/lib.rs
index 3a1b6346d..0fc3780f5 100644
--- a/forc-plugins/forc-doc/src/lib.rs
+++ b/forc-plugins/forc-doc/src/lib.rs
@@ -129,15 +129,24 @@ impl<'e> RenderPlan<'e> {
 
 pub struct DocContext {
     pub manifest: ManifestFile,
-    pub pkg_manifest: Option<Box<PackageManifestFile>>,
     pub doc_path: PathBuf,
     pub engines: Engines,
     pub build_plan: pkg::BuildPlan,
-    pub is_workspace: bool,
     pub workspace_name: String,
 }
 
 impl DocContext {
+    pub fn is_workspace(&self) -> bool {
+        matches!(self.manifest, ManifestFile::Workspace(_))
+    }
+
+    pub fn pkg_manifest(&self) -> Option<&PackageManifestFile> {
+        match &self.manifest {
+            ManifestFile::Package(pkg) => Some(pkg),
+            ManifestFile::Workspace(_) => None,
+        }
+    }
+
     pub fn from_options(opts: &Command) -> Result<Self> {
         // get manifest directory
         let dir = if let Some(ref path) = opts.path {
@@ -155,15 +164,6 @@ impl DocContext {
             .unwrap_or("workspace")
             .to_string();
 
-        // Handle Package vs Workspace manifests
-        let is_workspace = matches!(&manifest, ManifestFile::Workspace(_));
-
-        // Get package manifest for single packages (None for workspaces)
-        let pkg_manifest = match &manifest {
-            ManifestFile::Package(pkg_manifest) => Some(pkg_manifest.clone()),
-            ManifestFile::Workspace(_) => None,
-        };
-
         // create doc path
         let out_path = default_output_directory(manifest.dir());
         let doc_dir = opts
@@ -181,7 +181,7 @@ impl DocContext {
         let lock_path = manifest.lock_path()?;
 
         // Check for empty workspaces
-        if is_workspace && member_manifests.is_empty() {
+        if matches!(manifest, ManifestFile::Workspace(_)) && member_manifests.is_empty() {
             bail!("Workspace contains no members");
         }
 
@@ -196,23 +196,21 @@ impl DocContext {
 
         Ok(Self {
             manifest,
-            pkg_manifest,
             doc_path,
             engines: Engines::default(),
             build_plan,
-            is_workspace,
             workspace_name,
         })
     }
 }
 
 pub fn compile(ctx: &DocContext, opts: &Command) -> Result<impl Iterator<Item = Option<Programs>>> {
-    if ctx.is_workspace {
+    if ctx.is_workspace() {
         println_action_green(
             "Compiling",
             &format!("workspace ({})", ctx.manifest.dir().to_string_lossy()),
         );
-    } else if let Some(ref pkg_manifest) = ctx.pkg_manifest {
+    } else if let Some(pkg_manifest) = ctx.pkg_manifest() {
         println_action_green(
             "Compiling",
             &format!(
@@ -247,7 +245,7 @@ pub fn compile_html(
     let mut documented_libraries = Vec::new();
 
     let raw_docs = if opts.no_deps {
-        if let Some(ref pkg_manifest) = ctx.pkg_manifest {
+        if let Some(pkg_manifest) = ctx.pkg_manifest() {
             // Single package mode
             let Some(ty_program) = compile_results
                 .pop()
@@ -307,7 +305,7 @@ pub fn compile_html(
                 // Only document libraries that are workspace members
                 if matches!(ty_program.kind, TyProgramKind::Library { .. }) {
                     // Check if this package is a workspace member
-                    let is_workspace_member = if ctx.is_workspace {
+                    let is_workspace_member = if ctx.is_workspace() {
                         ctx.manifest.member_manifests()?.iter().any(|(_, member)| {
                             member.project_name() == pkg_manifest_file.project_name()
                         })
@@ -339,7 +337,7 @@ pub fn compile_html(
     };
 
     // Create workspace index if this is a workspace
-    if ctx.is_workspace && !documented_libraries.is_empty() {
+    if ctx.is_workspace() && !documented_libraries.is_empty() {
         // Sort libraries alphabetically for consistent display
         documented_libraries.sort_by(|a, b| a.name.cmp(&b.name));
         create_workspace_index(
@@ -352,13 +350,13 @@ pub fn compile_html(
 
     search::write_search_index(&ctx.doc_path, &raw_docs)?;
 
-    let result = if ctx.is_workspace {
+    let result = if ctx.is_workspace() {
         DocResult::Workspace {
             name: ctx.workspace_name.clone(),
             libraries: documented_libraries,
         }
-    } else if let Some(ref pkg_manifest) = ctx.pkg_manifest {
-        DocResult::Package(pkg_manifest.clone())
+    } else if let Some(pkg_manifest) = ctx.pkg_manifest() {
+        DocResult::Package(Box::new(pkg_manifest.clone()))
     } else {
         unreachable!("Should have either workspace or package")
     };

[JoshuaBatty]

Thanks for the suggestion @zees-dev. Applied here a57b398

[zees-dev]

LGTM 👍