godoc2md

package module
v0.0.0-...-4e7a98b Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 14, 2020 License: BSD-3-Clause Imports: 19 Imported by: 0

README

godoc2md

import "github.com/thatgerber/godoc2md"

Overview

Package godoc2md contains the code used to perform the CLI command godoc2md.

[![GoDoc](https://godoc.org/github.com/ThatGerber/godoc2md?status.svg)](https://godoc.org/github.com/ThatGerber/godoc2md)

This package is forked from https://github.com/davecheney/godoc2md which is no longer updated.

godoc2md converts godoc formatted package documentation into Markdown format.

# Generate Package Readme
$ godoc2md $PACKAGE > $GOPATH/src/$PACKAGE/README.md

# See all Options
$ godoc2md
  usage: godoc2md package [more-packages ...]
  -basePrefix go.mod
	  	path prefix of go files. If not set, cli will attempt to set it by checking go.mod, current directory, and the 1st position argument
  -ex
	  	show examples in command line mode
  -goroot GOROOT
	  	directory of Go Root. Will attempt to lookup from GOROOT
  -hashformat string
	  	source link URL hash format (default "#L%d")
  -links
	  	link identifiers to their declarations (default true)
  -play
	  	enable playground in web interface (default true)
  -srclink string
	  	if set, format for filename of source link
  -tabwidth int
	  	tab width (default 4)
  -template string
	  	path to an alternate template file
  -timestamps
	  	show timestamps with directory listings (default true)
  -urlPrefix string
	  	URL for generated URLs. (default "github.com")
  -v	verbose mode

Index

Package files

comment.go config.go doc.go funcs.go presentation.go template.go

Constants

const (
    URLScheme = "https"
)

Variables

var (

    // Config contains the configuration for the CLI. To populate config, call
    // `Parse()` and use the provided response.
    Config = &Cli{
        Verbose:           flag.Bool("v", false, "verbose mode"),
        Goroot:            flag.String("goroot", "", "directory of Go Root. Will attempt to lookup from `GOROOT`"),
        TabWidth:          flag.Int("tabwidth", 4, "tab width"),
        ShowTimestamps:    flag.Bool("timestamps", true, "show timestamps with directory listings"),
        BasePrefix:        flag.String("basePrefix", "", "path prefix of go files. If not set, cli will attempt to set it by checking `go.mod`, current directory, and the 1st position argument"),
        UrlPrefix:         flag.String("urlPrefix", defaultURLPrefix, "URL for generated URLs."),
        SourceID:          flag.String("sourceID", defaultSourceID, "URL for generated URLs."),
        AltPkgTemplate:    flag.String("template", "", "path to an alternate template file"),
        ShowPlayground:    flag.Bool("play", true, "enable playground in web interface"),
        ShowExamples:      flag.Bool("ex", false, "show examples in command line mode"),
        DeclLinks:         flag.Bool("links", true, "link identifiers to their declarations"),
        SrcLinkHashFormat: flag.String("hashformat", "#L%d", "source link URL hash format"),
        SrcLinkFormat:     flag.String("srclink", "", "if set, format for filename of source link"),
    }
)

var (
    TimeFormat = "2-Jan-2006 15:04:05 -0700"
)

func NewPresentation

func NewPresentation(corpus *godoc.Corpus, config *Cli) *godoc.Presentation

func ToMD

func ToMD(w io.Writer, text string)

ToMD converts comment text to formatted Markdown. The comment was prepared by DocReader, so it is known not to have leading, trailing blank lines nor to have trailing spaces at the end of lines. The comment markers have already been removed.

Each span of unindented non-blank lines is converted into a single paragraph. There is one exception to the rule: a span that consists of a single line, is followed by another paragraph span, begins with a capital letter, and contains no punctuation is formatted as a heading.

A span of indented lines is converted into a <pre> block, with the common indent prefix removed.

URLs in the comment text are converted into links.

type Cli

type Cli struct {
    Verbose *bool
    // Goroot
    Goroot *string

    // layout control
    TabWidth       *int
    ShowTimestamps *bool
    BasePrefix     *string
    UrlPrefix      *string
    SourceID       *string
    AltPkgTemplate *string
    ShowPlayground *bool
    ShowExamples   *bool
    DeclLinks      *bool

    // The hash format for Github is the default `#L%d`; but other source control platforms do not
    // use the same format. For example Bitbucket Enterprise uses `#%d`. This option provides the
    // user the option to switch the format as needed and still remain backwards compatible.
    SrcLinkHashFormat *string
    SrcLinkFormat     *string
}
func Parse
func Parse() ([]string, *Cli)

type TemplateUtils

type TemplateUtils struct {
    // contains filtered or unexported fields
}

TemplateUtils contains a collection of functions that can be used by the provided text template.

TemplateUtils most likely cannot be created directly, and a new instance should be created by calling NewTemplateUtils(config).

func NewTemplateUtils
func NewTemplateUtils(cfg *Cli) TemplateUtils

NewTemplateUtils returns a new TemplateUtils object configured from the provided CLI instance.

func (TemplateUtils) CommendToMD
func (t TemplateUtils) CommendToMD(comment string) string

CommendToMD converts the provided text, from Go source comment, into markdown.

func (TemplateUtils) GetCurrentTime
func (t TemplateUtils) GetCurrentTime() string

GetCurrentTime returns the current time in UTC using the configured format.

func (TemplateUtils) GetFullURL
func (t TemplateUtils) GetFullURL(pkg *godoc.PageInfo, decl ast.Decl) string

GetFullURL returns the URL, including line number, of the provided source code declaration.

func (TemplateUtils) GetSourceFileURL
func (t TemplateUtils) GetSourceFileURL(s string) string

GetSourceFileURL reads the provided string and converts it into a URL.

func (TemplateUtils) MDEscapeGo
func (t TemplateUtils) MDEscapeGo(text string) string

MDEscapeGo fences a string of text as Go Code.

func (TemplateUtils) MDEscapeInline
func (t TemplateUtils) MDEscapeInline(text string) string

MDEscapeInline escapes inline emphasis and bold marks.

func (TemplateUtils) Methods
func (t TemplateUtils) Methods() map[string]interface{}

Methods returns a map of name to func of all the methods of this struct. It's provided to the presenter and the keys are made available as functions to the template.

func (TemplateUtils) StripBasePrefix
func (t TemplateUtils) StripBasePrefix(path string) string

StripBasePrefix removes the configured basePrefix from the provided string.

Created: 14-Jul-2020 16:57:55 +0000 Generated by godoc2md

Documentation

Overview

Package godoc2md contains the code used to perform the CLI command `godoc2md`.

[![GoDoc](https://godoc.org/github.com/ThatGerber/godoc2md?status.svg)](https://godoc.org/github.com/ThatGerber/godoc2md)

This package is forked from https://github.com/davecheney/godoc2md which is no longer updated.

godoc2md converts godoc formatted package documentation into Markdown format. 

# Generate Package Readme
$ godoc2md $PACKAGE > $GOPATH/src/$PACKAGE/README.md

# See all Options
$ godoc2md
  usage: godoc2md package [more-packages ...]
  -basePrefix go.mod
	  	path prefix of go files. If not set, cli will attempt to set it by checking go.mod, current directory, and the 1st position argument
  -ex
	  	show examples in command line mode
  -goroot GOROOT
	  	directory of Go Root. Will attempt to lookup from GOROOT
  -hashformat string
	  	source link URL hash format (default "#L%d")
  -links
	  	link identifiers to their declarations (default true)
  -play
	  	enable playground in web interface (default true)
  -srclink string
	  	if set, format for filename of source link
  -tabwidth int
	  	tab width (default 4)
  -template string
	  	path to an alternate template file
  -timestamps
	  	show timestamps with directory listings (default true)
  -urlPrefix string
	  	URL for generated URLs. (default "github.com")
  -v	verbose mode

Index

Constants

View Source 
const (
	URLScheme = "https"
)

Variables

View Source 
var (

	// Config contains the configuration for the CLI. To populate config, call
	// `Parse()` and use the provided response.
	Config = &Cli{
		Verbose:           flag.Bool("v", false, "verbose mode"),
		Goroot:            flag.String("goroot", "", "directory of Go Root. Will attempt to lookup from `GOROOT`"),
		TabWidth:          flag.Int("tabwidth", 4, "tab width"),
		ShowTimestamps:    flag.Bool("timestamps", true, "show timestamps with directory listings"),
		BasePrefix:        flag.String("basePrefix", "", "path prefix of go files. If not set, cli will attempt to set it by checking `go.mod`, current directory, and the 1st position argument"),
		UrlPrefix:         flag.String("urlPrefix", defaultURLPrefix, "URL for generated URLs."),
		SourceID:          flag.String("sourceID", defaultSourceID, "URL for generated URLs."),
		AltPkgTemplate:    flag.String("template", "", "path to an alternate template file"),
		ShowPlayground:    flag.Bool("play", true, "enable playground in web interface"),
		ShowExamples:      flag.Bool("ex", false, "show examples in command line mode"),
		DeclLinks:         flag.Bool("links", true, "link identifiers to their declarations"),
		SrcLinkHashFormat: flag.String("hashformat", "#L%d", "source link URL hash format"),
		SrcLinkFormat:     flag.String("srclink", "", "if set, format for filename of source link"),
	}
)
View Source 
var (
	TimeFormat = "2-Jan-2006 15:04:05 -0700"
)

Functions

func NewPresentation 

func NewPresentation(corpus *godoc.Corpus, config *Cli) *godoc.Presentation

func ToMD 

func ToMD(w io.Writer, text string)

ToMD converts comment text to formatted Markdown. The comment was prepared by DocReader, so it is known not to have leading, trailing blank lines nor to have trailing spaces at the end of lines. The comment markers have already been removed.

Each span of unindented non-blank lines is converted into a single paragraph. There is one exception to the rule: a span that consists of a single line, is followed by another paragraph span, begins with a capital letter, and contains no punctuation is formatted as a heading.

A span of indented lines is converted into a `<pre>` block, with the common indent prefix removed.

URLs in the comment text are converted into links.

Types

type Cli 

type Cli struct {
	Verbose *bool
	// Goroot
	Goroot *string

	// layout control
	TabWidth       *int
	ShowTimestamps *bool
	BasePrefix     *string
	UrlPrefix      *string
	SourceID       *string
	AltPkgTemplate *string
	ShowPlayground *bool
	ShowExamples   *bool
	DeclLinks      *bool

	// The hash format for Github is the default `#L%d`; but other source control platforms do not
	// use the same format. For example Bitbucket Enterprise uses `#%d`. This option provides the
	// user the option to switch the format as needed and still remain backwards compatible.
	SrcLinkHashFormat *string
	SrcLinkFormat     *string
}

func Parse 

func Parse() ([]string, *Cli)

type TemplateUtils 

type TemplateUtils struct {
	// contains filtered or unexported fields
}

TemplateUtils contains a collection of functions that can be used by the provided text template.

TemplateUtils most likely cannot be created directly, and a new instance should be created by calling `NewTemplateUtils(config)`.

func NewTemplateUtils 

func NewTemplateUtils(cfg *Cli) TemplateUtils

NewTemplateUtils returns a new TemplateUtils object configured from the provided CLI instance.

func (TemplateUtils) CommendToMD 

func (t TemplateUtils) CommendToMD(comment string) string

CommendToMD converts the provided text, from Go source comment, into markdown.

func (TemplateUtils) GetCurrentTime 

func (t TemplateUtils) GetCurrentTime() string

GetCurrentTime returns the current time in UTC using the configured format.

func (TemplateUtils) GetFullURL 

func (t TemplateUtils) GetFullURL(pkg *godoc.PageInfo, decl ast.Decl) string

GetFullURL returns the URL, including line number, of the provided source code declaration.

func (TemplateUtils) GetSourceFileURL 

func (t TemplateUtils) GetSourceFileURL(s string) string

GetSourceFileURL reads the provided string and converts it into a URL.

func (TemplateUtils) MDEscapeGo 

func (t TemplateUtils) MDEscapeGo(text string) string

MDEscapeGo fences a string of text as Go Code.

func (TemplateUtils) MDEscapeInline 

func (t TemplateUtils) MDEscapeInline(text string) string

MDEscapeInline escapes inline emphasis and bold marks.

func (TemplateUtils) Methods 

func (t TemplateUtils) Methods() map[string]interface{}

Methods returns a map of name to func of all the methods of this struct. It's provided to the presenter and the keys are made available as functions to the template.

func (TemplateUtils) StripBasePrefix 

func (t TemplateUtils) StripBasePrefix(path string) string

StripBasePrefix removes the configured basePrefix from the provided string.

Source Files

View all Source files

Directories

Path Synopsis
cmd
godoc2md

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.