Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CreatePackageDocs ¶
func CreatePackageDocs(fs afero.Fs, repo Repo, templatePath string, excludedPackages ...string) error
CreatePackageDocs generates package documentation for a Go project using a specified template file. It first checks if the template file exists in the filesystem denoted by a provided afero.Fs instance. If it exists, the function walks the project directory, excluding any specified packages, and applies the template to each non-excluded package to generate its documentation.
**Parameters:**
fs: An afero.Fs instance representing the filesystem.
repo: A Repo instance containing the Go project's repository details.
templatePath: A string representing the path to the template file to be used for generating the package documentation.
excludedPackages: Zero or more strings representing the names of packages to be excluded from documentation generation.
**Returns:**
error: An error, if it encounters an issue while checking if the template file exists, walking the project directory, or generating the package documentation.
Example ¶
package main
import (
"fmt"
"path/filepath"
"github.com/l50/goutils/v2/docs"
"github.com/spf13/afero"
)
func main() {
// Mock the filesystem for testing
fs := afero.NewMemMapFs()
// Set up the repo details
repo := docs.Repo{
Owner: "l50", // Repository owner's name.
Name: "goutils", // Repository's name.
}
// Set the path to the template file
templatePath := filepath.Join("dev", "mage", "templates", "README.md.tmpl")
// Set the packages to exclude (optional)
excludedPkgs := []string{"excludedPkg1", "excludedPkg2"}
if err := docs.CreatePackageDocs(fs, repo, templatePath, excludedPkgs...); err != nil {
fmt.Printf("failed to create package docs: %v", err)
}
}
func FixCodeBlocks ¶
FixCodeBlocks processes a provided file to ensure that all code blocks within comments are surrounded by markdown fenced code block delimiters with the specified language.
**Parameters:** file: An object satisfying the File interface, which is to be processed. language: A string representing the language for the code blocks.
**Returns:** error: An error if there's an issue reading or writing the file.
Example ¶
package main
import (
"fmt"
"log"
"os"
"strings"
"github.com/l50/goutils/v2/docs"
fileutils "github.com/l50/goutils/v2/file/fileutils"
)
func main() {
input := `Driver represents an interface to Google Chrome using go.
It contains a context.Context associated with this Driver and
Options for the execution of Google Chrome.
` + "```go" + `
browser, err := cdpchrome.Init(true, true)
if err != nil {
log.Fatalf("failed to initialize a chrome browser: %v", err)
}
` + "```"
language := "go"
// Create a temporary file
tmpfile, err := os.CreateTemp("", "example.*.md")
if err != nil {
log.Printf("failed to create temp file: %v", err)
return
}
defer os.Remove(tmpfile.Name()) // clean up
// Write the input to the temp file
if _, err := tmpfile.Write([]byte(input)); err != nil {
log.Printf("failed to write to temp file: %v", err)
return
}
if err := tmpfile.Close(); err != nil {
log.Printf("failed to close temp file: %v", err)
return
}
// Run the function
file := fileutils.RealFile(tmpfile.Name())
err = docs.FixCodeBlocks(language, file)
if err != nil {
log.Printf("failed to fix code blocks: %v", err)
return
}
// Read the modified content
content, err := os.ReadFile(tmpfile.Name())
if err != nil {
log.Printf("failed to read file: %v", err)
return
}
// Print the result
fmt.Println(strings.TrimSpace(string(content)))
}
Output: Driver represents an interface to Google Chrome using go. It contains a context.Context associated with this Driver and Options for the execution of Google Chrome. ```go browser, err := cdpchrome.Init(true, true) if err != nil { log.Fatalf("failed to initialize a chrome browser: %v", err) } ```
Types ¶
type FuncInfo ¶
FuncInfo holds information about an exported function within a Go package.
**Attributes:**
FilePath: The path to the source file with the function declaration. FuncName: The name of the exported function.
type FunctionDoc ¶
type FunctionDoc struct {
Name string
Signature string
Description string
Params string
StructName string
}
FunctionDoc contains the documentation for a function within a Go package.
**Attributes:**
Name: The function name. Signature: The function signature, including parameters and return types. Description: The documentation or description of the function. Params: The function parameters.
type PackageDoc ¶
type PackageDoc struct {
PackageName string
Functions []FunctionDoc
GoGetPath string
}
PackageDoc holds the documentation for a Go package.
**Attributes:**
PackageName: The package name. Functions: A slice of FunctionDoc instances representing the functions. GoGetPath: The 'go get' path for the package.