chore(deps): bump github.com/spf13/cobra from 1.7.0 to 1.8.0

.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: "gomod" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/codacy.yml

@@ -0,0 +1,61 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# This workflow checks out code, performs a Codacy security scan
+# and integrates the results with the
+# GitHub Advanced Security code scanning feature.  For more information on
+# the Codacy security scan action usage and parameters, see
+# https://github.com/codacy/codacy-analysis-cli-action.
+# For more information on Codacy Analysis CLI in general, see
+# https://github.com/codacy/codacy-analysis-cli.
+
+name: Codacy Security Scan
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "master" ]
+  schedule:
+    - cron: '41 5 * * 3'
+
+permissions:
+  contents: read
+
+jobs:
+  codacy-security-scan:
+    permissions:
+      contents: read # for actions/checkout to fetch code
+      security-events: write # for github/codeql-action/upload-sarif to upload SARIF results
+      actions: read # only required for a private repository by github/codeql-action/upload-sarif to get the Action run status
+    name: Codacy Security Scan
+    runs-on: ubuntu-latest
+    steps:
+      # Checkout the repository to the GitHub Actions runner
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      # Execute Codacy Analysis CLI and generate a SARIF output with the security issues identified during the analysis
+      - name: Run Codacy Analysis CLI
+        uses: codacy/codacy-analysis-cli-action@d840f886c4bd4edc059706d09c6a1586111c540b
+        with:
+          # Check https://github.com/codacy/codacy-analysis-cli#project-token to get your project token from your Codacy repository
+          # You can also omit the token and run the tools that support default configurations
+          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+          verbose: true
+          output: results.sarif
+          format: sarif
+          # Adjust severity of non-security issues
+          gh-code-scanning-compat: true
+          # Force 0 exit code to allow SARIF file generation
+          # This will handover control about PR rejection to the GitHub side
+          max-allowed-issues: 2147483647
+
+      # Upload the SARIF file generated in the previous step
+      - name: Upload SARIF results file
+        uses: github/codeql-action/upload-sarif@v2
+        with:
+          sarif_file: results.sarif

.github/workflows/dependency-review.yml

@@ -0,0 +1,20 @@
+# Dependency Review Action
+#
+# This Action will scan dependency manifest files that change as part of a Pull Request, surfacing known-vulnerable versions of the packages declared or updated in the PR. Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable packages will be blocked from merging.
+#
+# Source repository: https://github.com/actions/dependency-review-action
+# Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement
+name: 'Dependency Review'
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 'Checkout Repository'
+        uses: actions/checkout@v3
+      - name: 'Dependency Review'
+        uses: actions/dependency-review-action@v3

.github/workflows/go.yml

@@ -0,0 +1,28 @@
+# This workflow will build a golang project
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
+
+name: Go
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.20'
+
+    - name: Build
+      run: go build -v ./...
+
+    - name: Test
+      run: go test -v ./...

.github/workflows/release.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Install Go
         uses: actions/setup-go@v1
         with:
-          go-version: 1.18.x
+          go-version: 1.20.x
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v1
         with:

.github/workflows/test.yml

@@ -17,7 +17,7 @@ jobs:
       - name: Install Go
         uses: actions/setup-go@v1
         with:
-          go-version: 1.18.x
+          go-version: 1.20.x
       - name: Checkout code
         uses: actions/checkout@v2
       - name: Lint

.golangci.yml

@@ -46,3 +46,7 @@ issues:
     - Error return value of .((os\.)?std(out|err)\..*|.*Close|.*Flush|os\.Remove(All)?|.*printf?|os\.(Un)?Setenv). is not checked
 
   exclude-use-default: false
+
+run:
+  skip-dirs:
+    - testData

.gomarkdoc.yml

@@ -1,10 +1,9 @@
 output: "{{.Dir}}/README.md"
-header: |+
+header: |-
   [![Go Report Card](https://goreportcard.com/badge/github.com/Weborama/gomarkdoc)](https://goreportcard.com/report/github.com/Weborama/gomarkdoc)
   [![GitHub Actions](https://github.com/Weborama/gomarkdoc/workflows/Test/badge.svg)](https://github.com/Weborama/gomarkdoc/actions?query=workflow%3ATest+branch%3Amaster)
   [![Go Reference](https://pkg.go.dev/badge/github.com/Weborama/gomarkdoc.svg)](https://pkg.go.dev/github.com/Weborama/gomarkdoc)
-  [![codecov](https://codecov.io/gh/princjef/gomarkdoc/branch/master/graph/badge.svg?token=171XNH5XLT)](https://codecov.io/gh/princjef/gomarkdoc)
-
+  [![codecov](https://codecov.io/gh/Weborama/gomarkdoc/branch/master/graph/badge.svg?token=171XNH5XLT)](https://codecov.io/gh/Weborama/gomarkdoc)
 repository:
   url: https://github.com/Weborama/gomarkdoc
   defaultBranch: master

README.md

@@ -40,6 +40,7 @@ Flags:
   -c, --check                              Check the output to see if it matches the generated documentation. --output must be specified to use this.
       --config string                      File from which to load configuration (default: .gomarkdoc.yml)
   -e, --embed                              Embed documentation into existing markdown files if available, otherwise append to file.
+      --exclude-dirs strings               List of package directories to ignore when producing documentation.
       --footer string                      Additional content to inject at the end of each output file.
       --footer-file string                 File containing additional content to inject at the end of each output file.
   -f, --format string                      Format to use for writing output data. Valid options: github (default), azure-devops, plain (default "github")
@@ -68,6 +69,14 @@ gomarkdoc --output doc.md .
 
 The gomarkdoc tool supports generating documentation for both local packages and remote ones. To specify a local package, start the name of the package with a period \(.\) or specify an absolute path on the filesystem. All other package signifiers are assumed to be remote packages. You may specify both local and remote packages in the same command invocation as separate arguments.
 
+If you have a project with many packages but you want to skip documentation generation for some, you can use the \-\-exclude\-dirs option. This will remove any matching directories from the list of directories to process. Excluded directories are specified using the same pathing syntax as the packages to process. Multiple expressions may be comma\-separated or specified by using the \-\-exclude\-dirs flag multiple times.
+
+For example, in this repository we generate documentation for the entire project while excluding our test packages by running:
+
+```
+gomarkdoc --exclude-dirs ./testData/... ./...
+```
+
 ### Output Redirection
 
 By default, the documentation generated by the gomarkdoc command is sent to standard output, where it can be redirected to a file. This can be useful if you want to perform additional modifications to the documentation or send it somewhere other than a file. However, keep in mind that there are some inconsistencies in how various shells/platforms handle redirected command output \(for example, Powershell encodes in UTF\-16, not UTF\-8\). As a result, the \-\-output option described below is recommended for most use cases.
@@ -88,44 +97,28 @@ You can see all of the data available to the output template in the PackageSpec
 
 The documentation information that is output is formatted using a series of text templates for the various components of the overall documentation which get generated. Higher level templates contain lower level templates, but any template may be replaced with an override template using the \-\-template/\-t option. The full list of templates that may be overridden are:
 
-```
-- file:    generates documentation for a file containing one or more
-           packages, depending on how the tool is configured. This is the
-           root template for documentation generation.
+- file: generates documentation for a file containing one or more packages, depending on how the tool is configured. This is the root template for documentation generation.
 
 - package: generates documentation for an entire package.
 
-- type:    generates documentation for a single type declaration, as well
-           as any related functions/methods.
+- type: generates documentation for a single type declaration, as well as any related functions/methods.
 
-- func:    generates documentation for a single function or method. It may
-           be referenced from within a type, or directly in the package,
-           depending on nesting.
+- func: generates documentation for a single function or method. It may be referenced from within a type, or directly in the package, depending on nesting.
 
-- value:   generates documentation for a single variable or constant
-           declaration block within a package.
+- value: generates documentation for a single variable or constant declaration block within a package.
 
-- index:   generates an index of symbols within a package, similar to what
-           is seen for godoc.org. The index links to types, funcs,
-           variables, and constants generated by other templates, so it may
-           need to be overridden as well if any of those templates are
-           changed in a material way.
+- index: generates an index of symbols within a package, similar to what is seen for godoc.org. The index links to types, funcs, variables, and constants generated by other templates, so it may need to be overridden as well if any of those templates are changed in a material way.
 
-- example: generates documentation for a single example for a package or
-           one of its symbols. The example is generated alongside whichever
-           symbol it represents, based on the standard naming conventions
-           outlined in https://blog.golang.org/examples#TOC_4.
+- example: generates documentation for a single example for a package or one of its symbols. The example is generated alongside whichever symbol it represents, based on the standard naming conventions outlined in https://blog.golang.org/examples#TOC_4.
 
-- doc:     generates the freeform documentation block for any of the above
-           structures that can contain a documentation section.
+- doc: generates the freeform documentation block for any of the above structures that can contain a documentation section.
 
-- import:  generates the import code used to pull in a package.
-```
+- import: generates the import code used to pull in a package.
 
-Overriding with the \-t option uses a key\-vaule pair mapping a template name to the file containing the contents of the override template to use. Specified template files must exist:
+Overriding with the \-\-template\-file option uses a key\-value pair mapping a template name to the file containing the contents of the override template to use. Specified template files must exist:
 
 ```
-gomarkdoc -t package=custom-package.gotxt -t doc=custom-doc.gotxt .
+gomarkdoc --template-file package=custom-package.gotxt --template-file doc=custom-doc.gotxt .
 ```
 
 ### Additional Options
@@ -245,19 +238,21 @@ Know of another project that is using gomarkdoc? Open an issue with a descriptio
 
 ## Index
 
-- [type Renderer](<#type-renderer>)
-  - [func NewRenderer(opts ...RendererOption) (*Renderer, error)](<#func-newrenderer>)
-  - [func (out *Renderer) Example(ex *lang.Example) (string, error)](<#func-renderer-example>)
-  - [func (out *Renderer) File(file *lang.File) (string, error)](<#func-renderer-file>)
-  - [func (out *Renderer) Func(fn *lang.Func) (string, error)](<#func-renderer-func>)
-  - [func (out *Renderer) Package(pkg *lang.Package) (string, error)](<#func-renderer-package>)
-  - [func (out *Renderer) Type(typ *lang.Type) (string, error)](<#func-renderer-type>)
-- [type RendererOption](<#type-rendereroption>)
-  - [func WithFormat(format format.Format) RendererOption](<#func-withformat>)
-  - [func WithTemplateOverride(name, tmpl string) RendererOption](<#func-withtemplateoverride>)
+- [type Renderer](<#Renderer>)
+  - [func NewRenderer\(opts ...RendererOption\) \(\*Renderer, error\)](<#NewRenderer>)
+  - [func \(out \*Renderer\) Example\(ex \*lang.Example\) \(string, error\)](<#Renderer.Example>)
+  - [func \(out \*Renderer\) File\(file \*lang.File\) \(string, error\)](<#Renderer.File>)
+  - [func \(out \*Renderer\) Func\(fn \*lang.Func\) \(string, error\)](<#Renderer.Func>)
+  - [func \(out \*Renderer\) Package\(pkg \*lang.Package\) \(string, error\)](<#Renderer.Package>)
+  - [func \(out \*Renderer\) Type\(typ \*lang.Type\) \(string, error\)](<#Renderer.Type>)
+- [type RendererOption](<#RendererOption>)
+  - [func WithFormat\(format format.Format\) RendererOption](<#WithFormat>)
+  - [func WithTemplateFunc\(name string, fn any\) RendererOption](<#WithTemplateFunc>)
+  - [func WithTemplateOverride\(name, tmpl string\) RendererOption](<#WithTemplateOverride>)
 
 
-## type [Renderer](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L15-L19>)
+<a name="Renderer"></a>
+## type [Renderer](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L16-L21>)
 
 Renderer provides capabilities for rendering various types of documentation with the configured format and templates.
 
@@ -267,78 +262,96 @@ type Renderer struct {
 }
 ```
 
-### func [NewRenderer](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L30>)
+<a name="NewRenderer"></a>
+### func [NewRenderer](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L32>)
 
 ```go
 func NewRenderer(opts ...RendererOption) (*Renderer, error)
 ```
 
 NewRenderer initializes a Renderer configured using the provided options. If nothing special is provided, the created renderer will use the default set of templates and the GitHubFlavoredMarkdown.
 
-### func \(\*Renderer\) [Example](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L140>)
+<a name="Renderer.Example"></a>
+### func \(\*Renderer\) [Example](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L135>)
 
 ```go
 func (out *Renderer) Example(ex *lang.Example) (string, error)
 ```
 
 Example renders an example's documentation to a string. You can change the rendering of the example by overriding the "example" template or one of the templates it references.
 
-### func \(\*Renderer\) [File](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L112>)
+<a name="Renderer.File"></a>
+### func \(\*Renderer\) [File](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L107>)
 
 ```go
 func (out *Renderer) File(file *lang.File) (string, error)
 ```
 
 File renders a file containing one or more packages to document to a string. You can change the rendering of the file by overriding the "file" template or one of the templates it references.
 
-### func \(\*Renderer\) [Func](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L126>)
+<a name="Renderer.Func"></a>
+### func \(\*Renderer\) [Func](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L121>)
 
 ```go
 func (out *Renderer) Func(fn *lang.Func) (string, error)
 ```
 
 Func renders a function's documentation to a string. You can change the rendering of the package by overriding the "func" template or one of the templates it references.
 
-### func \(\*Renderer\) [Package](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L119>)
+<a name="Renderer.Package"></a>
+### func \(\*Renderer\) [Package](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L114>)
 
 ```go
 func (out *Renderer) Package(pkg *lang.Package) (string, error)
 ```
 
 Package renders a package's documentation to a string. You can change the rendering of the package by overriding the "package" template or one of the templates it references.
 
-### func \(\*Renderer\) [Type](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L133>)
+<a name="Renderer.Type"></a>
+### func \(\*Renderer\) [Type](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L128>)
 
 ```go
 func (out *Renderer) Type(typ *lang.Type) (string, error)
 ```
 
 Type renders a type's documentation to a string. You can change the rendering of the type by overriding the "type" template or one of the templates it references.
 
-## type [RendererOption](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L22>)
+<a name="RendererOption"></a>
+## type [RendererOption](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L24>)
 
 RendererOption configures the renderer's behavior.
 
 ```go
 type RendererOption func(renderer *Renderer) error
 ```
 
-### func [WithFormat](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L102>)
+<a name="WithFormat"></a>
+### func [WithFormat](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L83>)
 
 ```go
 func WithFormat(format format.Format) RendererOption
 ```
 
 WithFormat changes the renderer to use the format provided instead of the default format.
 
-### func [WithTemplateOverride](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L88>)
+<a name="WithTemplateFunc"></a>
+### func [WithTemplateFunc](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L97>)
 
 ```go
-func WithTemplateOverride(name, tmpl string) RendererOption
+func WithTemplateFunc(name string, fn any) RendererOption
 ```
 
-WithTemplateOverride adds a template that overrides the template with the provided name using the value provided in the tmpl parameter.
+WithTemplateFunc adds the provided function with the given name to the list of functions that can be used by the rendering templates.
+
+Any name collisions between built\-in functions and functions provided here are resolved in favor of the function provided here, so be careful about the naming of your functions to avoid overriding existing behavior unless desired.
 
+<a name="WithTemplateOverride"></a>
+### func [WithTemplateOverride](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L69>)
 
+```go
+func WithTemplateOverride(name, tmpl string) RendererOption
+```
+
+WithTemplateOverride adds a template that overrides the template with the provided name using the value provided in the tmpl parameter.
 
 Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)