From ed79d5030d8525ccde334de4d6a1cf255d5dedcb Mon Sep 17 00:00:00 2001 From: LandonTClipp <11232769+LandonTClipp@users.noreply.github.com> Date: Wed, 1 Jan 2025 18:57:03 -0600 Subject: [PATCH] doc updates --- docs/configuration.md | 69 +++++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 35 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 6821e546..8a100016 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -3,6 +3,40 @@ Configuration mockery uses [spf13/viper](https://github.com/spf13/viper) under the hood for its configuration parsing. +Parameter Descriptions +----------------------- + +!!! success "new style `packages` config" + The [`packages`]() config section is the new style of configuration. All old config semantics, including `go:generate` and any config files lacking the `packages` section is officially deprecated as of v2.31.0. Legacy semantics will be completely removed in v3. + + Please see the [features section](features.md#packages-configuration) for more details on how `packages` works, including some example configuration. + + Please see the [migration docs](migrating_to_packages.md) for details on how to migrate your config. + +| name | templated | default | description | +|--------------------------------------------------------|---------------------------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `all` | :fontawesome-solid-x: | `#!yaml false` | Generate all interfaces for the specified packages. | +| `_anchors` | :fontawesome-solid-x: | `#!yaml {}` | Unused by mockery, but allowed in the config schema so that you may define arbitrary yaml anchors. | +| `boilerplate-file` | :fontawesome-solid-x: | `#!yaml ""` | Specify a path to a file that contains comments you want displayed at the top of all generated mock files. This is commonly used to display license headers at the top of your source code. | +| `config` | :fontawesome-solid-x: | `#!yaml ""` | Set the location of the mockery config file. | +| `dir` | :fontawesome-solid-check: | `#!yaml "mocks/{{.SrcPackagePath}}"` | The directory where the mock file will be outputted to. | +| `exclude` | :fontawesome-solid-x: | `#!yaml []` | Specify subpackages to exclude when using `#!yaml recursive: True` | +| `exclude-regex` | :fontawesome-solid-x: | `#!yaml ""` | When set along with `include-regex`, then interfaces which match `include-regex` but also match `exclude-regex` will not be generated. If `all` is set, or if `include-regex` is not set, then `exclude-regex` has no effect. | +| `filename` | :fontawesome-solid-check: | `#!yaml "mock_{{.InterfaceName}}.go"` | The name of the file the mock will reside in. | +| `formatter` | :fontawesome-solid-x: | `#!yaml "goimports"` | The formatter to use on the rendered template. Choices are: `gofmt`, `goimports`, `noop`. | +| `include-regex` | :fontawesome-solid-x: | `#!yaml ""` | When set, only interface names that match the expression will be generated. This setting is ignored if `all: True` is specified in the configuration. To further refine the interfaces generated, use `exclude-regex`. | +| `log-level` | :fontawesome-solid-x: | `#!yaml "info"` | Set the level of the logger | +| `mock-build-tags` | :fontawesome-solid-x: | `#!yaml ""` | Set the build tags of the generated mocks. Read more about the [format](https://pkg.go.dev/cmd/go#hdr-Build_constraints). | +| `mockname` | :fontawesome-solid-check: | `#!yaml "Mock{{.InterfaceName}}"` | The name of the generated mock. | +| `outpkg` | :fontawesome-solid-check: | `#!yaml "{{.PackageName}}"` | Use `outpkg` to specify the package name of the generated mocks. | +| [`packages`](features.md#packages-configuration) | :fontawesome-solid-x: | `#!yaml null` | A dictionary containing configuration describing the packages and interfaces to generate mocks for. | +| `pkgname` | :fontawesome-solid-check: | `#!yaml "{{.SrcPackageName}}" | The `#!go package name` given to the generated mock files. | +| [`recursive`](features.md#recursive-package-discovery) | :fontawesome-solid-x: | `#!yaml false` | When set to `true` on a particular package, mockery will recursively search for all sub-packages and inject those packages into the config map. | +| `tags` | :fontawesome-solid-x: | `#!yaml ""` | A space-separated list of additional build tags to load packages. | +| `template` | :fontawesome-solid-x: | `#!yaml ""` | The template to use. The choices are `moq`, `mockery`, or a file path provided by `file://path/to/file.txt`. | +| `template-data` | :fontawesome-solid-x: | `#!yaml {}` | A `map[string]any` that provides arbitrary options to the template. Each template will have a different set of accepted keys. Refer to each template's documentation for more details. | + + Merging Precedence ------------------ @@ -46,41 +80,6 @@ mockery will search upwards from your current-working-directory up to the root p See the [`features` section](features.md#examples) for more details on how the config is structured. -Parameter Descriptions ------------------------ - -!!! success "new style `packages` config" - The [`packages`]() config section is the new style of configuration. All old config semantics, including `go:generate` and any config files lacking the `packages` section is officially deprecated as of v2.31.0. Legacy semantics will be completely removed in v3. - - Please see the [features section](features.md#packages-configuration) for more details on how `packages` works, including some example configuration. - - Please see the [migration docs](migrating_to_packages.md) for details on how to migrate your config. - -| name | templated | default | description | -|--------------------------------------------------------|---------------------------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `all` | :fontawesome-solid-x: | `#!yaml false` | Generate all interfaces for the specified packages. | -| `_anchors` | :fontawesome-solid-x: | `#!yaml {}` | Unused by mockery, but allowed in the config schema so that you may define arbitrary yaml anchors. | -| `boilerplate-file` | :fontawesome-solid-x: | `#!yaml ""` | Specify a path to a file that contains comments you want displayed at the top of all generated mock files. This is commonly used to display license headers at the top of your source code. | -| `config` | :fontawesome-solid-x: | `#!yaml ""` | Set the location of the mockery config file. | -| `dir` | :fontawesome-solid-check: | `#!yaml "mocks/{{.SrcPackagePath}}"` | The directory where the mock file will be outputted to. | -| `exclude` | :fontawesome-solid-x: | `#!yaml []` | Specify subpackages to exclude when using `#!yaml recursive: True` | -| `exclude-regex` | :fontawesome-solid-x: | `#!yaml ""` | When set along with `include-regex`, then interfaces which match `include-regex` but also match `exclude-regex` will not be generated. If `all` is set, or if `include-regex` is not set, then `exclude-regex` has no effect. | -| `filename` | :fontawesome-solid-check: | `#!yaml "mock_{{.InterfaceName}}.go"` | The name of the file the mock will reside in. | -| `formatter` | :fontawesome-solid-x: | `#!yaml "goimports"` | The formatter to use on the rendered template. Choices are: `gofmt`, `goimports`, `noop`. | -| `include-regex` | :fontawesome-solid-x: | `#!yaml ""` | When set, only interface names that match the expression will be generated. This setting is ignored if `all: True` is specified in the configuration. To further refine the interfaces generated, use `exclude-regex`. | -| `log-level` | :fontawesome-solid-x: | `#!yaml "info"` | Set the level of the logger | -| `mock-build-tags` | :fontawesome-solid-x: | `#!yaml ""` | Set the build tags of the generated mocks. Read more about the [format](https://pkg.go.dev/cmd/go#hdr-Build_constraints). | -| `mockname` | :fontawesome-solid-check: | `#!yaml "Mock{{.InterfaceName}}"` | The name of the generated mock. | -| `outpkg` | :fontawesome-solid-check: | `#!yaml "{{.PackageName}}"` | Use `outpkg` to specify the package name of the generated mocks. | -| [`packages`](features.md#packages-configuration) | :fontawesome-solid-x: | `#!yaml null` | A dictionary containing configuration describing the packages and interfaces to generate mocks for. | -| `pkgname` | :fontawesome-solid-check: | `#!yaml "{{.SrcPackageName}}" | The `#!go package name` given to the generated mock files. | -| `print` | :fontawesome-solid-x: | `#!yaml false` | Use `print: True` to have the resulting code printed out instead of written to disk. | -| [`recursive`](features.md#recursive-package-discovery) | :fontawesome-solid-x: | `#!yaml false` | When set to `true` on a particular package, mockery will recursively search for all sub-packages and inject those packages into the config map. | -| [`replace-type`](features.md#replace-types) | :fontawesome-solid-x: | `#!yaml null` | Replaces aliases, packages and/or types during generation. | -| `tags` | :fontawesome-solid-x: | `#!yaml ""` | A space-separated list of additional build tags to load packages. | -| `template` | :fontawesome-solid-x: | `#!yaml ""` | The template to use. The choices are `moq`, `mockery`, or a file path provided by `file://path/to/file.txt`. | -| `template-data` | :fontawesome-solid-x: | `#!yaml {}` | A `map[string]any` that provides arbitrary options to the template. Each template will have a different set of accepted keys. Refer to each template's documentation for more details. | - Layouts -------