Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(deps): bump github.com/spf13/viper from 1.16.0 to 1.18.1 #19

Closed
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
1144eca
chore(deps): update to go 1.20 and latest golangci-lint (#85)
princjef Feb 6, 2023
bbe4470
feat: use go1.19 documentation parsing to parse documentation blocks …
princjef Feb 24, 2023
7d0c2ca
fix(templates): fix inconsistent spacing (#88)
princjef Feb 24, 2023
cc78abb
feat: add support for links in documentation (#89)
princjef Apr 2, 2023
cac02fa
feat(cmd) add diff to --check output (#95)
princjef Jun 11, 2023
88639c6
docs(readme): fix option for template overriding in example (#92)
ccamel Jun 11, 2023
5e37559
feat(lang): update examples to better match godoc/pkg.go.dev (#69)
ThatsMrTalbot Jun 11, 2023
43f2be8
ci: improve coverage measurement (#96)
princjef Jun 11, 2023
7f25ccf
feat(format): escape link text (#97)
princjef Jun 11, 2023
0124a63
feat(format): allow template funcs to be customized (#98)
princjef Jun 12, 2023
c546771
Merge remote-tracking branch 'upstream/master'
gglachant Jun 15, 2023
f8aab49
fix(lang): only print url for auto links (#100)
princjef Jun 16, 2023
e62c5ab
feat(cmd): add --exclude-dirs option (#101)
princjef Jun 17, 2023
cf14929
Create dependency-review.yml
peczenyj Aug 18, 2023
85e735d
Create codacy.yml
peczenyj Aug 18, 2023
5a9107a
Create go.yml
peczenyj Aug 18, 2023
8d2305c
Create dependabot.yml
peczenyj Aug 18, 2023
9559677
chore(deps): bump golang.org/x/net from 0.4.0 to 0.7.0
dependabot[bot] Aug 18, 2023
7058f90
chore(deps): bump golang.org/x/crypto
dependabot[bot] Aug 18, 2023
31961de
Merge pull request #1 from princjef/master
gglachant Aug 18, 2023
4bbe45d
Merge pull request #2 from Weborama/peczenyj-patch-1
gglachant Aug 18, 2023
a1801ea
Merge pull request #3 from Weborama/peczenyj-patch-4
gglachant Aug 18, 2023
99d2a59
Merge pull request #4 from Weborama/peczenyj-patch-5
gglachant Aug 18, 2023
aae123d
Merge pull request #5 from Weborama/peczenyj-patch-6
gglachant Aug 18, 2023
edb1cae
Merge pull request #6 from Weborama/dependabot/go_modules/golang.org/…
gglachant Aug 18, 2023
9831f07
chore(deps): bump mvdan.cc/xurls/v2 from 2.2.0 to 2.5.0
dependabot[bot] Aug 18, 2023
6634173
chore(deps): bump github.com/matryer/is from 1.4.0 to 1.4.1
dependabot[bot] Aug 18, 2023
0c930d1
Merge branch 'master' into dependabot/go_modules/golang.org/x/crypto-…
gglachant Aug 18, 2023
30646a8
Merge pull request #7 from Weborama/dependabot/go_modules/golang.org/…
gglachant Aug 18, 2023
fb5b8e6
Merge pull request #8 from Weborama/dependabot/go_modules/mvdan.cc/xu…
gglachant Aug 18, 2023
2ee779b
chore(deps): bump github.com/spf13/cobra from 1.1.3 to 1.7.0
dependabot[bot] Aug 18, 2023
1a37eae
Merge pull request #9 from Weborama/dependabot/go_modules/github.com/…
gglachant Aug 18, 2023
863c172
Merge pull request #10 from Weborama/dependabot/go_modules/github.com…
gglachant Aug 18, 2023
f06edfe
chore(deps): bump github.com/spf13/viper from 1.7.1 to 1.16.0
dependabot[bot] Aug 18, 2023
d40db38
Merge pull request #11 from Weborama/dependabot/go_modules/github.com…
gglachant Aug 18, 2023
b1f5603
chore(deps): bump github.com/go-git/go-git/v5 from 5.3.0 to 5.8.1
dependabot[bot] Aug 18, 2023
d5b5ec2
Merge pull request #12 from Weborama/dependabot/go_modules/github.com…
gglachant Aug 18, 2023
1e4c14c
Bump github.com/sirupsen/logrus to v1.9.3
gglachant Aug 18, 2023
45d5e74
chore(deps): bump github.com/spf13/viper from 1.16.0 to 1.18.1
dependabot[bot] Dec 11, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
@@ -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"
61 changes: 61 additions & 0 deletions .github/workflows/codacy.yml
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions .github/workflows/dependency-review.yml
Original file line number Diff line number Diff line change
@@ -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
28 changes: 28 additions & 0 deletions .github/workflows/go.yml
Original file line number Diff line number Diff line change
@@ -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 ./...
2 changes: 1 addition & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions .golangci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
5 changes: 2 additions & 3 deletions .gomarkdoc.yml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
109 changes: 61 additions & 48 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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.

Expand All @@ -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>)
Loading
Loading