Forc Doc

Sway 语言的文档器。

快速入门

先决条件

• 必须安装 forc。
• 必须在包含 Forc.toml 和一些成功编译的 Sway 代码的目录或父目录中。
• 要显示文档，只需将 doc 属性添加到可文档化的项中，例如

  /// Defines my contract ABI...
  abi MyContractABI {}
  

• 您也可以使用模块级别的 doc 属性语法在模块级别进行文档化

  注意：这只能在 Sway 文件的开始处工作

  //! Library containing types used for...
  library;
  

  查看Sway参考的doc属性部分，以获取更多有关如何记录Sway代码的信息。doc属性部分

如果您已通过fuelup安装了分布式工具链，您已经有了运行forc doc所需的一切。否则，您可以通过cargo install install安装forc和forc doc，或者直接从fuelup安装。

以下命令检查您是否已具备运行forc doc所需的一切。

$ cd my_fuel_project
$ ls # check Forc.toml exists
# src Forc.toml
$ forc --version # check forc is installed
$ forc doc --version # check forc doc is installed
$ forc doc --open # open docs in default browser

有关用法，请参阅手册。

要为开发安装forc doc，请参阅入门部分，位于贡献部分下。

贡献

欢迎！我们很高兴您来这里帮忙。以下是对程序设计选择的概述，以及如何在本地构建forc doc并测试您的更改。

构建要求

• cargo
• forc
• 默认的现代浏览器（旧浏览器可能会引起问题）

提示：如果您看不到任何变化生效，可能是由于存在多个forc doc二进制文件。为了防止这种情况，请删除任何优先存在的现有版本，例如fuelup二进制文件。您也可以通过执行cargo run来避免这种情况，请参阅查看更改。

$ which forc-doc
# ~/.fuelup/bin/forc-doc
$ rm ~/.fuelup/bin/forc-doc
$ which forc-doc
# if it displays nothing, you're good to go!

入门

将sway仓库克隆到您喜欢的目录中

$ git clone https://github.com/FuelLabs/sway.git

然后进入新创建的sway目录，并安装forc doc

$ cd sway
$ cargo install --path forc-plugins/forc-doc

太好了！让我们检查一切是否按预期工作。尝试在一个测试目录中运行forc doc

$ forc doc --manifest-path src/tests/data/impl_traits --open

如果成功，您应该在浏览器中看到测试文档。

开发

新的语言关键字？想添加功能？更新CSS？forc doc已经设置为使开发变得容易。

设计概述

项目的每个部分都标有相应的功能。

• doc：文档阶段。处理编译后的类型化Sway程序的分析，并将有用的信息收集到Documents中，以便渲染到HTML。如果您正在尝试实现新的Sway语言功能或使有关现有功能的某些信息可用于渲染，请从这里开始。
• render：将文档阶段收集的信息渲染成HTML，并将其放置在out/doc目录中。此阶段特别适合熟悉构建静态HTML网页的人。使用宏来编写与编写纯HTML非常相似的HTML的horrorshow库。
• licenses：使用字体、标志或与项目相关的任何需要许可证的内容时，必须在由forc doc生成的文档中存在的文件。
• static.files：为了使样式生效，必须在由forc doc生成的文档中存在的文件，例如CSS、图标和字体。
• tests/data：这是Sway代码边缘情况的所在地。如果出现边缘情况错误，请编写最小化复现并将其放置在此处以开始。

在forc-doc项目目录中运行cargo doc，以深入了解每个部分的责任！

文档阶段

可文档化项

添加新的可文档化项非常简单。可文档化项只有两种形式，声明（TyDecl）和上下文（其他所有内容）。

声明可以直接添加到分析阶段的描述，位于descriptor.rs。只需将新的TyDecl添加到from_typed_decl的匹配臂中，并填写必要的字段以生成包装的DescriptorDocument，然后将其作为Documentable返回。

上下文项，例如结构体上的字段、枚举的变体等，必须添加到位于context.rs的ContextType枚举中，并在其对应的TyDecl分析时收集。ContextType被包装在Context结构体中，稍后将其排序并渲染到RenderedDocument的ItemContext中。

示例

假设我们想要有一个新的声明类型，称为CoolNewDecl，其模式与StructDecl相同，但具有特殊用途。

首先，我们将声明的上下文添加到ContextType作为一个变体

// in context.rs
pub(crate) enum ContextType {
    // Add in the new declaration's context type
    CoolNewFields(Vec<TyCoolNewField>),
    /* ... */
}

然后匹配新的声明并返回Document。

// in descriptor.rs
pub(crate) enum Descriptor {
    Documentable(Document),
    NonDocumentable,
}
impl Descriptor {
    pub(crate) fn from_typed_decl(/* ... */) -> Result<Self> {
        match ty_decl {
            // Add the new declaration to the match arm
            ty::TyDecl::CoolNewDecl(ty::CoolNewDecl { decl_id, .. }) => {
                let decl = decl_engine.get_cool_new_decl(decl_id);
                if !document_private_items && decl.visibility.is_private() {
                    Ok(Descriptor::NonDocumentable)
                } else {
                    let item_name = decl.call_path.suffix;
                    let attrs_opt = (!decl.attributes.is_empty())
                        .then(|| decl.attributes.to_html_string());
                    // Fill in the context of the new declaration
                    let context = (!decl.fields.is_empty()).then_some(Context::new(
                        module_info.clone(),
                        ContextType::CoolNewFields(decl.fields),
                    ));

                    Ok(Descriptor::Documentable(Document {
                        module_info: module_info.clone(),
                        item_header: ItemHeader {
                            module_info: module_info.clone(),
                            friendly_name: ty_decl.friendly_type_name(),
                            item_name: item_name.clone(),
                        },
                        item_body: ItemBody {
                            module_info,
                            ty_decl: ty_decl.clone(),
                            item_name,
                            code_str: swayfmt::parse::parse_format::<sway_ast::ItemCoolNew>(
                                decl.span.as_str(),
                            )?,
                            attrs_opt: attrs_opt.clone(),
                            item_context: ItemContext {
                                context_opt: context,
                                impl_traits: None,
                            },
                        },
                        raw_attributes: attrs_opt,
                    }))
                }
            }
            /* ... */
            _ => Ok(Descriptor::NonDocumentable),
        }
    }
}

一旦声明被收集到Document中，就可以渲染Document。有关如何将新的可文档化项添加到Document中的详细信息，请参考位于render/mod.rs的RenderedDocumentation上的from_raw_docs方法。在那里你可以找到大量如何将Document渲染为RenderedDocument的示例。

索引文件生成

索引文件，如 AllDocIndex、ProjectIndex 和 ModuleIndex，仅使用从 Sway 模块收集的信息进行渲染。它们的渲染过程也可以在 RenderedDocumentation::from_raw_docs 方法中找到。ModuleInfo 是在从 TyProgram 生成 Documentation 时收集的，TyProgram 可以在 doc/mod.rs 中找到。这是整个分析过程的起点，其中 TyProgram 被编译并传递给 Documentation::from_ty_program。

渲染阶段

如前所述，在 forc doc 中，渲染相对直接，因为 HTML 是一个通用网页的。

让我们一起写一个小型的渲染端示例，使用 horrorshow 库。

这是 docs.rs 搜索栏的 HTML。

<nav class="sub">
  <form class="search-form">
    <div class="search-container">
      <span></span>
      <input
        class="search-input"
        name="search"
        autocomplete="off"
        spellcheck="false"
        placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
        type="search"
      />
      <div id="help-button" title="help" tabindex="-1">
        <a href="../help.html">?</a>
      </div>
      <div id="settings-menu" tabindex="-1">
        <a href="../settings.html" title="settings">
          <img
            width="22"
            height="22"
            alt="change settings"
            src="../static.files/wheel-7b819b6101059cd0.svg"
          />
        </a>
      </div>
    </div>
  </form>
</nav>

这是产生相同 HTML 的相应 horrorshow 代码。

mod search {
    use horrorshow::{box_html, RenderBox};

    pub(crate) fn generate_searchbar() -> Box<dyn RenderBox> {
        box_html! {
            nav(class="sub") {
                form(class="search-form") {
                    div(class="search-container") {
                        span;
                        input(
                            class="search-input",
                            name="search",
                            autocomplete="off",
                            spellcheck="false",
                            placeholder="Click or press ‘S’ to search, ‘?’ for more options…",
                            type="search"
                        );
                        div(id="help-button", title="help", tabindex="-1") {
                            a(href="../help.html") { : "?" }
                        }
                        div(id="settings-menu", tabindex="-1") {
                            a(href="../settings.html", title="settings") {
                                img(
                                    width="22",
                                    height="22",
                                    alt="change settings",
                                    src="../static.files/wheel-7b819b6101059cd0.svg"
                                )
                            }
                        }
                    }
                }
            }
        }
    }
}

现在我们可以在需要为网页生成搜索栏时随时调用这个函数！

查看更改

一旦做出了一些更改，运行 forc doc 二进制文件，传递包含 Forc.toml 的路径。

cargo run -- --manifest-path path/to/manifest --open

提示： VS Code 用户？尝试 Live Server 插件，可以使查看更改更加容易。它会在更新时重新加载网页，因此您只需要重新构建文档（cargo run -- --manifest-path path/to/manifest）。只需在 VS Code 中右键点击由 forc doc 生成的文档索引文件，该文件位于 out/doc 目录中，并选择“使用 Live Server 打开”选项。搞定！