package
0.2.0
Repository: https://github.com/dubbikins/godoc-readme.git
Documentation: pkg.go.dev

# README

Package godoc_readme

godoc-readme badge

Implements the godocs parsing and README generation from template files.

Types

type PackageReadme

type PackageReadme struct {
   Options ReadmeOptions
   Pkg     *packages.Package
   Doc     *doc.Package
   bytes.Buffer
   rel_file_path string
   file_name     string
   file          *os.File
   cwd           string
   rejected      bool
}

PackageReadme is a struct that holds the package, ast and docs of the package It's used to pass data to the readme template

type Readme

type Readme struct {
   Pkgs                       map[string]*packages.Package
   TestPkgs                   map[string]*packages.Package
   pkgs                       []*packages.Package
   options                    *ReadmeOptions
   readmes                    []*PackageReadme
   confirmation_listener      net.Listener
   confirmation_listener_port int
   confirmation_server        *http.Server
}

Readme is a struct that holds the packages, ast and docs of the package And is used to pass data to the readme template

classDiagram
   class Readme
   Readme : +map[string]*packages.Package Pkgs
   Readme : -[]*packages.Package pkgs
   Readme : -ReadmeOptions options
   Readme : +Generate() error
   Readme --> ReadmeOptions
   Readme --> PackageReadme
   class ReadmeOptions
   ReadmeOptions : -string Dir
   ReadmeOptions : -string DirPattern
   ReadmeOptions : -string TemplateFile
   class PackageReadme
   PackageReadme : +ReadmeOptions Options
   PackageReadme : +packages.Package Pkg
   PackageReadme : +doc.Package Doc

[!NOTE] Because of the simpicity of godoc-readme's templating engine, you can add powerful customizations to your documentation like the class diagram that was created using a code block and the mermaid.js library that is supported out of the box with Github markdown. (not all features are supported though.)


Methods

method Generate

func (readme *Readme) Generate() (err error)

Generate creates the README.md file for the packages that are registered with a Readme

The README is generated in the directory of the package using the template file provided or the default template in none is provided. The following template functions available in the template engine are defined in the template_functions package:

FunctionDescriptionExampleOutput
exampleRenders a markdown representation of a [doc.Example] instance{{ example . }} where . is a [doc.Example]renders an example like
codeRenders the start (or end) of a code block in markdown, optionally specifying the language format of the code block{{ code "go" }}fmt.Println("Hello World"){{ code }} ```go\nfmt.Println("Hello World")\n```\n
fmtRenders a formatted string representation of an [ast.Node]{{ fmt . }}N/A
linkRenders a markdown link to the location of the [ast.Node] in a package{{ link "title" . }}[title](...) where ... is the relative link to the file ,including line numbers
alertRenders a markdown alert message based on the notes provided in the [doc.Package]{{ alert . "title" }}renders the alerts with the "title" target
sectionRenders an indented markdown section header{{ section "line 1 text\nline 2 text" 1}}>line 1 text\n>line 2 text
docRenders a package's doc string, including in-line alerts, package ref's, etc{{ doc . }}N/A
relative_pathReplaces the pwd the .{{ relative_path "/abs/path" }} where /abs is the pwdreturns ./path

Additionally, the following functions are available in the template engine:

  • base: [filepath.Base] Returns the base name of a file path
ExampleReadme_Generate
func ExampleReadme_Generate{
    readme, err := NewReadme(func(ro *ReadmeOptions) {
        ro.Dir = "../examples/mermaid"
    })
    if err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
    if err = readme.Generate(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }

}
 // Output:
 // 

type ReadmeOptions

type ReadmeOptions struct {
   PackageDir        string
   Dir               string
   Format            func([]byte) []byte
   package_load_mode packages.LoadMode
   Env               []string `env:"-"`
   ConfirmUpdates    bool
   Flags             template_functions.Flags
}

ReadmeOptions is a struct that holds the options for the Readme struct You can set the options via the options functions or by setting the environment variables defined in the env struct tag for the Option field

type RenderFlag

type RenderFlag uint32

RenderFlags can be used to turn on and off rendering of different sections in the README.md file.

The bitmask values are as follows:

1234567...32
TypesFuncsTypeMethodsVarsConstsExamplesAlertsTBDRenderAll (default)

For example, to render only the types and functions in the README.md file, you would set the 1st and 2nd bits, i.e 0000 0011 or RenderTypes | RenderFuncs


Methods

method IsSet

func (f RenderFlag) IsSet(flag RenderFlag) bool

IsSet returns true if the flag is set in the RenderFlags


Functions

func FormatMarkdown

func FormatMarkdown(md []byte) []byte

FormatMarkdown applies the following formatting to the markdown:

  1. Replace all hard-tabs(\t) with 4 single space characters ( )
  2. Remove leading whitespace from blank lines
  3. Replace multiple \n(3+) with a single \n

Vars

// The readme templates are embedded in the binary so that it can be used as a default template
// This value can be overridden by providing a template file using the --template flag or the GODOC_README_TEMPLATE_FILE environment variable
//
//go:embed templates/*
var readme_templates embed.FS

# Packages

Package template_functions This package provides a set of functions that are passed to the template engine to generate documentation.

# Functions

FormatMarkdown applies the following formatting to the markdown: 1.
NewReadme creates a new Readme struct that holds the packages, ast and docs of the package It loads the packages in the directory provided and parses the ast and docs of the package It returns an error if the packages failed to load The options are provided as functional options Usage: ```go readme, err := NewReadme(func(ro *ReadmeOptions) { ro.Dir = "./path/to/package" ro.DirPattern = "./path/to/package/..." }) ```.

# Constants

RenderFlags can be used to turn on and off rendering of different sections in the README.md file.
RenderFlags can be used to turn on and off rendering of different sections in the README.md file.
RenderFlags can be used to turn on and off rendering of different sections in the README.md file.
RenderFlags can be used to turn on and off rendering of different sections in the README.md file.
RenderFlags can be used to turn on and off rendering of different sections in the README.md file.
RenderFlags can be used to turn on and off rendering of different sections in the README.md file.
RenderFlags can be used to turn on and off rendering of different sections in the README.md file.
RenderFlags can be used to turn on and off rendering of different sections in the README.md file.

# Structs

PackageReadme is a struct that holds the package, ast and docs of the package It's used to pass data to the readme template.
Readme is a struct that holds the packages, ast and docs of the package And is used to pass data to the readme template ```mermaid classDiagram class Readme Readme : +map[string]*packages.Package Pkgs Readme : -[]*packages.Package pkgs Readme : -ReadmeOptions options Readme : +Generate() error Readme --> ReadmeOptions Readme --> PackageReadme class ReadmeOptions ReadmeOptions : -string Dir ReadmeOptions : -string DirPattern ReadmeOptions : -string TemplateFile class PackageReadme PackageReadme : +ReadmeOptions Options PackageReadme : +packages.Package Pkg PackageReadme : +doc.Package Doc ``` */.
ReadmeOptions is a struct that holds the options for the Readme struct You can set the options via the options functions or by setting the environment variables defined in the `env` struct tag for the Option field.

# Type aliases

RenderFlags can be used to turn on and off rendering of different sections in the README.md file.