build

Documentation

Overview

Package build 提供构建文档的相关功能

Index

• Constants
• func Buffer(h *core.MessageHandler, o *Output, i ...*Input) (*bytes.Buffer, error)
• func Build(h *core.MessageHandler, o *Output, i ...*Input) error
• func CheckSyntax(h *core.MessageHandler, i ...*Input) error
• func ParseInputs(blocks chan core.Block, h *core.MessageHandler, opt ...*Input)
• type Config
  • func DetectConfig(wd core.URI, recursive bool) (*Config, error)
  • func LoadConfig(wd core.URI) (*Config, error)
  • func (cfg *Config) Buffer(h *core.MessageHandler) *bytes.Buffer
  • func (cfg *Config) Build(h *core.MessageHandler)
  • func (cfg *Config) CheckSyntax(h *core.MessageHandler)
  • func (cfg *Config) Save(wd core.URI) (err error)
• type Input
  • func (o *Input) ParseFile(blocks chan core.Block, h *core.MessageHandler, uri core.URI)
• type Output

Constants

const (
	APIDocXML   = "apidoc+xml"
	OpenapiYAML = "openapi+yaml"
	OpenapiJSON = "openapi+json"
)

几种输出的类型

Functions

func Buffer

func Buffer(h *core.MessageHandler, o *Output, i ...*Input) (*bytes.Buffer, error)

Buffer 生成文档内容并返回

如果是配置文件有问题，则直接返回错误信息，文档错误则输出至 h 对象。

func Build

func Build(h *core.MessageHandler, o *Output, i ...*Input) error

Build 解析文档并输出文档内容

如果是配置文件有问题，则直接返回错误信息，文档错误则输出至 h 对象。

func CheckSyntax

func CheckSyntax(h *core.MessageHandler, i ...*Input) error

CheckSyntax 测试文档语法

如果是配置文件有问题，则直接返回错误信息，文档错误则输出至 h 对象。

func ParseInputs

func ParseInputs(blocks chan core.Block, h *core.MessageHandler, opt ...*Input)

ParseInputs 分析 opt 中所指定的内容并输出到 blocks

分析后的内容推送至 blocks 中。

Types

type Config

type Config struct {
	// 文档的版本信息
	//
	// 程序会用此来判断程序的兼容性。
	Version string `yaml:"version"`

	// 输入的配置项，可以指定多个项目
	//
	// 多语言项目，可能需要用到多个输入面。
	Inputs []*Input `yaml:"inputs"`

	// 输出配置项
	Output *Output `yaml:"output"`
}

Config 配置文件映身的结构

func DetectConfig

func DetectConfig(wd core.URI, recursive bool) (*Config, error)

DetectConfig 检测 wd 内容并生成 Config 实例

wd 只能为本地文件系统； recursive 是否检测子目录；

func LoadConfig

func LoadConfig(wd core.URI) (*Config, error)

LoadConfig 加载指定目录下的配置文件

func (*Config) Buffer

func (cfg *Config) Buffer(h *core.MessageHandler) *bytes.Buffer

Buffer 根据 wd 目录下的配置文件生成文档内容并保存至内存

具体信息可参考 Buffer 函数的相关文档。

func (*Config) Build

func (cfg *Config) Build(h *core.MessageHandler)

Build 解析文档并输出文档内容

具体信息可参考 Build 函数的相关文档。

func (*Config) CheckSyntax

func (cfg *Config) CheckSyntax(h *core.MessageHandler)

CheckSyntax 执行对语法内容的测试

func (*Config) Save

func (cfg *Config) Save(wd core.URI) (err error)

Save 将内容保存至 wd 目录下的 .apidoc.yaml 文件

保存时会将各个与路径相关的字段尽量改成与 wd 相关的相对路径。

type Input

type Input struct {
	Lang      string   `yaml:"lang"`                // 输入的目标语言，值为 internal/lang 中的 Language.ID
	Dir       core.URI `yaml:"dir"`                 // 源代码目录
	Exts      []string `yaml:"exts,omitempty"`      // 需要扫描的文件扩展名，为空则表示采用默认规则。
	Recursive bool     `yaml:"recursive,omitempty"` // 是否查找 Dir 的子目录
	Encoding  string   `yaml:"encoding,omitempty"`  // 源文件的编码，默认为 UTF-8
	Ignores   []string `yaml:"ignores,omitempty"`   // 忽略的文件或目录，比如 node_modules 等可在此指定
	// contains filtered or unexported fields
}

Input 指定输入内容的相关信息。

func (*Input) ParseFile

func (o *Input) ParseFile(blocks chan core.Block, h *core.MessageHandler, uri core.URI)

ParseFile 分析 uri 指向的文件并输出到 blocks

type Output

type Output struct {
	// 文档的版本号
	//
	// 该值会覆盖文档中 apidoc.version 的值，方便用户通过代码层面进行版本号同步，
	// 该值无法通过配置文件设置，只能由代码进行设置。
	Version string `yaml:"-"`

	// 导出的文件类型格式，默认为 apidoc 的 XML 文件。
	Type string `yaml:"type,omitempty"`

	// 文档的保存路径
	//
	// 仅适用本地路径
	Path core.URI `yaml:"path"`

	// 只输出该标签的文档，若为空，则表示所有。
	Tags []string `yaml:"tags,omitempty"`

	// xslt 文件地址
	//
	// 默认值为 https://apidoc.tools/docs/ 下当前版本的 apidoc.xsl，比如：
	//  https://apidoc.tools/docs/v7/apidoc.xsl
	//
	// NOTE: 仅针对 xml 类型的输出文件
	Style string `yaml:"style,omitempty"`

	// 命名空间的相关设置
	//
	// 当 namespace 为 true 时会在文档中输出以 core.XMLNamespace 作为命名空间的值，
	// 如果还指定了 NamespacePrefix 则会以此值作为前缀值。
	// NamespacePrefix 仅在 Namespace 为 true 时才启作用。
	//
	// NOTE: 仅针对 Type = APIDocXML
	Namespace       bool   `yaml:"namespace,omitempty"`
	NamespacePrefix string `yaml:"namespace-prefix,omitempty"`
	// contains filtered or unexported fields
}

Output 指定了渲染输出的相关设置项。