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.

Sign up for GitHub

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

docs(readme): change default examples to use --output option #45

Merged
merged 1 commit into from
Jun 22, 2021
Merged

docs(readme): change default examples to use --output option #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
12 changes: 9 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ Flags:
The gomarkdoc command processes each of the provided packages\, generating documentation for the package in markdown format and writing it to console\. For example\, if you have a package in your current directory and want to send it to a documentation markdown file\, you might do something like this:

```
gomarkdoc . > doc.md
gomarkdoc --output doc.md .
```

### Package Specifiers
Expand All @@ -61,7 +61,13 @@ The gomarkdoc tool supports generating documentation for both local packages and

### Output Redirection

If you want to redirect output for each processed package to a file\, you can alternatively provide the \-\-output/\-o option\, which accepts a template specifying how to generate the path of the output file\. A common usage of this option is when generating README documentation for a package with subpackages \(which are supported via the \.\.\. signifier available in other tools\):
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\.

```
gomarkdoc . > doc.md
```

If you want to redirect output for each processed package to a file\, you can provide the \-\-output/\-o option\, which accepts a template specifying how to generate the path of the output file\. A common usage of this option is when generating README documentation for a package with subpackages \(which are supported via the \.\.\. signifier as in other parts of the golang toolchain\)\. In addition\, this option provides consistent behavior across platforms and shells:

```
gomarkdoc --output '{{.Dir}}/README.md' ./...
Expand Down Expand Up @@ -116,7 +122,7 @@ gomarkdoc -t package=custom-package.gotxt -t doc=custom-doc.gotxt .
As with the godoc tool itself\, only exported symbols will be shown in documentation\. This can be expanded to include all symbols in a package by adding the \-\-include\-unexported/\-u flag\.

```
gomarkdoc -u . > README.md
gomarkdoc -u -o README.md .
```

You can also run gomarkdoc in a verification mode with the \-\-check/\-c flag\. This is particularly useful for continuous integration when you want to make sure that a commit correctly updated the generated documentation\. This flag is only supported when the \-\-output/\-o flag is specified\, as the file provided there is what the tool is checking:
Expand Down
25 changes: 18 additions & 7 deletions doc.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
// For example, if you have a package in your current directory and want to
// send it to a documentation markdown file, you might do something like this:
//
// gomarkdoc . > doc.md
// gomarkdoc --output doc.md .
//
// Package Specifiers
//
Expand All @@ -57,12 +57,23 @@
//
// 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.
//
// gomarkdoc . > doc.md
//
// If you want to redirect output for each processed package to a file, you can
// alternatively provide the --output/-o option, which accepts a template
// specifying how to generate the path of the output file. A common usage of
// this option is when generating README documentation for a package with
// subpackages (which are supported via the ... signifier available in other
// tools):
// provide the --output/-o option, which accepts a template specifying how to
// generate the path of the output file. A common usage of this option is when
// generating README documentation for a package with subpackages (which are
// supported via the ... signifier as in other parts of the golang toolchain).
// In addition, this option provides consistent behavior across platforms and
// shells:
//
// gomarkdoc --output '{{.Dir}}/README.md' ./...
//
Expand Down Expand Up @@ -120,7 +131,7 @@
// documentation. This can be expanded to include all symbols in a package by
// adding the --include-unexported/-u flag.
//
// gomarkdoc -u . > README.md
// gomarkdoc -u -o README.md .
//
// You can also run gomarkdoc in a verification mode with the --check/-c flag.
// This is particularly useful for continuous integration when you want to make
Expand Down