feat(forge): doc

Cargo.toml

@@ -10,6 +10,7 @@ members = [
     "cli/test-utils",
     "common",
     "config",
+    "doc",
     "evm",
     "fmt",
     "forge",

cli/Cargo.toml

@@ -13,6 +13,7 @@ vergen = { version = "7.0", default-features = false, features = ["build", "rust
 [dependencies]
 # foundry internal
 forge-fmt = { path = "../fmt" }
+forge-doc = { path = "../doc" }
 foundry-utils = { path = "../utils" }
 forge = { path = "../forge" }
 foundry-config = { path = "../config" }

cli/assets/.gitignoreTemplate

@@ -7,5 +7,8 @@ out/
 /broadcast/*/31337/
 /broadcast/**/dry-run/
 
+# Docs
+docs/
+
 # Dotenv file
 .env

cli/src/cmd/forge/doc.rs

@@ -0,0 +1,101 @@
+use crate::{cmd::Cmd, opts::GH_REPO_PREFIX_REGEX};
+use clap::{Parser, ValueHint};
+use forge_doc::{ContractInheritance, DocBuilder, GitSource, Inheritdoc, Server};
+use foundry_config::{find_project_root_path, load_config_with_root};
+use std::{path::PathBuf, process::Command};
+
+#[derive(Debug, Clone, Parser)]
+pub struct DocArgs {
+    #[clap(
+        help = "The project's root path.",
+        long_help = "The project's root path. By default, this is the root directory of the current Git repository, or the current working directory.",
+        long,
+        value_hint = ValueHint::DirPath,
+        value_name = "PATH"
+    )]
+    root: Option<PathBuf>,
+
+    #[clap(
+        help = "The doc's output path.",
+        long_help = "The output path for the generated mdbook. By default, it is the `docs/` in project root.",
+        long = "out",
+        short,
+        value_hint = ValueHint::DirPath,
+        value_name = "PATH"
+    )]
+    out: Option<PathBuf>,
+
+    #[clap(help = "Build the `mdbook` from generated files.", long, short)]
+    build: bool,
+
+    #[clap(help = "Serve the documentation.", long, short)]
+    serve: bool,
+
+    #[clap(help = "Hostname for serving documentation.", long, requires = "serve")]
+    hostname: Option<String>,
+
+    #[clap(help = "Port for serving documentation.", long, short, requires = "serve")]
+    port: Option<usize>,
+}
+
+impl Cmd for DocArgs {
+    type Output = ();
+
+    fn run(self) -> eyre::Result<Self::Output> {
+        let root = self.root.clone().unwrap_or(find_project_root_path()?);
+        let config = load_config_with_root(Some(root.clone()));
+
+        let mut doc_config = config.doc.clone();
+        if let Some(out) = self.out {
+            doc_config.out = out;
+        }
+        if doc_config.repository.is_none() {
+            // Attempt to read repo from git
+            if let Ok(output) = Command::new("git").args(["remote", "get-url", "origin"]).output() {
+                if !output.stdout.is_empty() {
+                    let remote = String::from_utf8(output.stdout)?.trim().to_owned();
+                    if let Some(captures) = GH_REPO_PREFIX_REGEX.captures(&remote) {
+                        let brand = captures.name("brand").unwrap().as_str();
+                        let tld = captures.name("tld").unwrap().as_str();
+                        let project = GH_REPO_PREFIX_REGEX.replace(&remote, "");
+                        doc_config.repository = Some(format!(
+                            "https://{brand}.{tld}/{}",
+                            project.trim_end_matches(".git")
+                        ));
+                    }
+                }
+            }
+        }
+
+        let commit =
+            Command::new("git").args(["rev-parse", "HEAD"]).output().ok().and_then(|output| {
+                if !output.stdout.is_empty() {
+                    String::from_utf8(output.stdout).ok().map(|commit| commit.trim().to_owned())
+                } else {
+                    None
+                }
+            });
+
+        DocBuilder::new(root.clone(), config.project_paths().sources)
+            .with_should_build(self.build)
+            .with_config(doc_config.clone())
+            .with_fmt(config.fmt)
+            .with_preprocessor(ContractInheritance::default())
+            .with_preprocessor(Inheritdoc::default())
+            .with_preprocessor(GitSource {
+                root,
+                commit,
+                repository: doc_config.repository.clone(),
+            })
+            .build()?;
+
+        if self.serve {
+            Server::new(doc_config.out)
+                .with_hostname(self.hostname.unwrap_or("localhost".to_owned()))
+                .with_port(self.port.unwrap_or(3000))
+                .serve()?;
+        }
+
+        Ok(())
+    }
+}

cli/src/cmd/forge/mod.rs

@@ -46,6 +46,7 @@ pub mod config;
 pub mod coverage;
 pub mod create;
 pub mod debug;
+pub mod doc;
 pub mod flatten;
 pub mod fmt;
 pub mod fourbyte;

cli/src/forge.rs

@@ -116,6 +116,9 @@ fn main() -> eyre::Result<()> {
         Subcommands::Geiger(cmd) => {
             cmd.run()?;
         }
+        Subcommands::Doc(cmd) => {
+            cmd.run()?;
+        }
     }
 
     Ok(())

cli/src/opts/dependency.rs

@@ -7,7 +7,8 @@ use std::str::FromStr;
 static GH_REPO_REGEX: Lazy<Regex> =
     Lazy::new(|| Regex::new("[A-Za-z\\d-]+/[A-Za-z\\d_.-]+").unwrap());
 
-static GH_REPO_PREFIX_REGEX: Lazy<Regex> = Lazy::new(|| {
+/// Git repo prefix regex
+pub static GH_REPO_PREFIX_REGEX: Lazy<Regex> = Lazy::new(|| {
     Regex::new(r"((git@)|(git\+https://)|(https://)|(org-([A-Za-z0-9-])+@))?(?P<brand>[A-Za-z0-9-]+)\.(?P<tld>[A-Za-z0-9-]+)(/|:)")
         .unwrap()
 });

cli/src/opts/forge.rs

@@ -5,6 +5,7 @@ use crate::cmd::forge::{
     config, coverage,
     create::CreateArgs,
     debug::DebugArgs,
+    doc::DocArgs,
     flatten,
     fmt::FmtArgs,
     fourbyte::UploadSelectorsArgs,
@@ -149,6 +150,9 @@ pub enum Subcommands {
         about = "Detects usage of unsafe cheat codes in a foundry project and its dependencies."
     )]
     Geiger(geiger::GeigerArgs),
+
+    #[clap(about = "Generate documentation for the project.")]
+    Doc(DocArgs),
 }
 
 // A set of solc compiler settings that can be set via command line arguments, which are intended

cli/tests/it/config.rs

@@ -108,6 +108,7 @@ forgetest!(can_extract_config_values, |prj: TestProject, mut cmd: TestCommand| {
         build_info: false,
         build_info_path: None,
         fmt: Default::default(),
+        doc: Default::default(),
         fs_permissions: Default::default(),
         __non_exhaustive: (),
         __warnings: vec![],

cli/tests/it/doc.rs

@@ -0,0 +1,11 @@
+use foundry_cli_test_utils::util::{setup_forge_remote, RemoteProject};
+
+#[test]
+fn can_generate_solmate_docs() {
+    let (prj, _) =
+        setup_forge_remote(RemoteProject::new("transmissions11/solmate").set_build(false));
+    prj.forge_command()
+        .args(["doc", "--build"])
+        .ensure_execute_success()
+        .expect("`forge doc` failed");
+}

cli/tests/it/main.rs

@@ -9,6 +9,8 @@ mod config;
 #[cfg(not(feature = "external-integration-tests"))]
 mod create;
 #[cfg(not(feature = "external-integration-tests"))]
+mod doc;
+#[cfg(not(feature = "external-integration-tests"))]
 mod multi_script;
 #[cfg(not(feature = "external-integration-tests"))]
 mod script;

config/src/doc.rs

@@ -0,0 +1,29 @@
+//! Configuration specific to the `forge doc` command and the `forge_doc` package
+
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+
+/// Contains the config for parsing and rendering docs
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct DocConfig {
+    /// Doc output path.
+    pub out: PathBuf,
+    /// The documentation title.
+    pub title: String,
+    /// Path to user provided `book.toml`.
+    pub book: PathBuf,
+    /// The repository url.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub repository: Option<String>,
+}
+
+impl Default for DocConfig {
+    fn default() -> Self {
+        Self {
+            out: PathBuf::from("docs"),
+            book: PathBuf::from("book.toml"),
+            title: String::default(),
+            repository: None,
+        }
+    }
+}

config/src/lib.rs

@@ -64,6 +64,9 @@ pub use crate::fs_permissions::FsPermissions;
 pub mod error;
 pub use error::SolidityErrorCode;
 
+pub mod doc;
+pub use doc::DocConfig;
+
 mod warning;
 pub use warning::*;
 
@@ -333,6 +336,8 @@ pub struct Config {
     pub build_info_path: Option<PathBuf>,
     /// Configuration for `forge fmt`
     pub fmt: FormatterConfig,
+    /// Configuration for `forge doc`
+    pub doc: DocConfig,
     /// Configures the permissions of cheat codes that touch the file system.
     ///
     /// This includes what operations can be executed (read, write)
@@ -384,7 +389,7 @@ impl Config {
 
     /// Standalone sections in the config which get integrated into the selected profile
     pub const STANDALONE_SECTIONS: &'static [&'static str] =
-        &["rpc_endpoints", "etherscan", "fmt", "fuzz", "invariant"];
+        &["rpc_endpoints", "etherscan", "fmt", "doc", "fuzz", "invariant"];
 
     /// File name of config toml file
     pub const FILE_NAME: &'static str = "foundry.toml";
@@ -1740,6 +1745,7 @@ impl Default for Config {
             build_info: false,
             build_info_path: None,
             fmt: Default::default(),
+            doc: Default::default(),
             __non_exhaustive: (),
             __warnings: vec![],
         }

doc/Cargo.toml

@@ -0,0 +1,47 @@
+[package]
+name = "forge-doc"
+version = "0.1.0"
+edition = "2021"
+description = """
+Foundry's solidity doc parsing
+"""
+license = "MIT OR Apache-2.0"
+readme = "README.md"
+
+[dependencies]
+# foundry internal
+foundry-common = { path = "../common" }
+forge-fmt = { path = "../fmt" }
+foundry-config = { path = "../config" }
+
+# ethers
+ethers-solc = { git = "https://github.com/gakonst/ethers-rs", default-features = false, features = ["async"] }
+ethers-core = { git = "https://github.com/gakonst/ethers-rs", default-features = false }
+
+# cli
+clap = { version = "3.0.10", features = [
+    "derive",
+    "env",
+    "unicode",
+    "wrap_help",
+] }
+
+# mdbook
+mdbook = { version = "0.4.25", default-features = false }
+warp = { version = "0.3.2", default-features = false, features = ["websocket"] }
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+futures-util = "0.3.4"
+
+# misc
+solang-parser = "=0.1.18"
+eyre = "0.6"
+thiserror = "1.0.30"
+rayon = "1.5.1"
+itertools = "0.10.3"
+toml = "0.5"
+auto_impl = "1"
+derive_more = "0.99"
+once_cell = "1.13"
+
+[dev-dependencies]
+assert_matches = "1.5.0"

doc/README.md

@@ -0,0 +1,27 @@
+# Documentation (`doc`)
+
+Solidity documentation generator. It parses the source code and generates an mdbook
+based on the parse tree and [NatSpec comments](https://docs.soliditylang.org/en/v0.8.17/natspec-format.html).
+
+## Architecture
+
+The entrypoint for the documentation module is the `DocBuilder`.
+The `DocBuilder` generates the mdbook in 3 phases:
+
+1. Parse
+
+In this phase, builder invokes 2 parsers: [solang parser](https://github.com/hyperledger-labs/solang) and internal `Parser`. The solang parser produces the parse tree based on the source code. Afterwards, the internal parser walks the parse tree by implementing the `Visitor` trait from the `fmt` crate and saves important information about the parsed nodes, doc comments.
+
+Then, builder takes the output of the internal `Parser` and creates documents with additional information: the path of the original item, display identity, the target path where this document will be written.
+
+
+2. Preprocess
+
+The builder accepts an array of preprocessors which can be applied to documents produced in the `Parse` phase. The preprocessors can rearrange and/or change the array as well as modify the separate documents.
+
+At the end of this phase, the builder maintains a possibly modified collection of documents.
+
+
+3. Write
+
+At this point, builder has all necessary information to generate documentation for the source code. It takes every document, formats the source file contents and writes/copies additional files that are required for building documentation.