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) } }
Output:
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.