gsd

package module
v0.0.0-...-3cca90f Latest Latest
Warning

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

 Go to latest Published: Sep 12, 2020 License: MIT Imports: 34 Imported by: 0

README

gsd (go simple doc)

Install
go get -u github.com/miclle/gsd/cmd/gsd
Generate documentation
cd project
gsd
Start documentation webserver
gsd -http=:3000

then open http://localhost:3000

Documentation

Overview

Package gsd documentation extracts source code documentation from Go Doc and Go AST.

Index

Constants

View Source 
const Version = "0.0.1"

Version info

Variables

This section is empty.

Functions

func FormatSelections 

func FormatSelections(w io.Writer, text []byte, lw LinkWriter, links Selection, sw SegmentWriter, selections ...Selection)

FormatSelections takes a text and writes it to w using link and segment writers lw and sw as follows: lw is invoked for consecutive segment starts and ends as specified through the links selection, and sw is invoked for consecutive segments of text overlapped by the same selections as specified by selections. The link writer lw may be nil, in which case the links Selection is ignored.

func FormatText 

func FormatText(w io.Writer, text []byte, line int, goSource bool, pattern string, selection Selection)

FormatText HTML-escapes text and writes it to w. Consecutive text segments are wrapped in HTML spans (with tags as defined by startTags and endTag) as follows:

  • if line >= 0, line number (ln) spans are inserted before each line, starting with the value of line
  • if the text is Go source, comments get the "comment" span class
  • each occurrence of the regular expression pattern gets the "highlight" span class
  • text segments covered by selection get the "selection" span class

Comments, highlights, and selections may overlap arbitrarily; the respective HTML span classes are specified in the startTags variable.

func IsExported 

func IsExported(name string) bool

IsExported check first letter is capital

func LinkifyText 

func LinkifyText(w io.Writer, text []byte, n ast.Node)

LinkifyText HTML-escapes source text and writes it to w. Identifiers that are in a "use" position (i.e., that are not being declared), are wrapped with HTML links pointing to the respective declaration, if possible. Comments are formatted the same way as with FormatText.

func TypeFields 

func TypeFields(t *Type) (fields []*ast.Field)

TypeFields get type fields

Types

type Corpus 

type Corpus struct {
	Path string

	// Packages is all packages cache
	Packages map[string]*Package

	// Tree is packages tree struct
	// - a
	// 	- a-a
	// - b
	//
	Tree Packages

	EnablePrivateIndent bool
	// contains filtered or unexported fields
}

A Corpus holds all the package documentation

func NewCorpus 

func NewCorpus(path string) (*Corpus, error)

NewCorpus return a new Corpus

func (*Corpus) DocumentHandler 

func (c *Corpus) DocumentHandler(w http.ResponseWriter, req *http.Request)

DocumentHandler serve documents The "/" pattern matches everything, so we need to check that we're at the root here.

func (*Corpus) Export 

func (c *Corpus) Export() (err error)

Export store documents

func (*Corpus) IndentFilter 

func (c *Corpus) IndentFilter(nodes interface{}) (result interface{})

IndentFilter indent filter

func (*Corpus) InitVersionInfo 

func (c *Corpus) InitVersionInfo()

InitVersionInfo parses the $GOROOT/api/go*.txt API definition files to discover which API features were added in which Go releases.

func (*Corpus) ParsePackages 

func (c *Corpus) ParsePackages() error

ParsePackages return packages

func (*Corpus) StaticHandler 

func (c *Corpus) StaticHandler(w http.ResponseWriter, req *http.Request)

StaticHandler serve static assets

func (*Corpus) Watch 

func (c *Corpus) Watch(address string) (err error)

Watch server

type Field 

type Field struct {
	*ast.Field
	Type *Type
}

Field type

func (Field) JoinNames 

func (f Field) JoinNames() (names []string)

JoinNames return names array

type FieldsPage 

type FieldsPage struct {
	Package *Package
	Fields  []*Field
	Expand  bool
}

FieldsPage fields page type

type Func 

type Func struct {

	// doc.Func
	Doc  string
	Name string
	Decl *ast.FuncDecl

	// methods
	// (for functions, these fields have the respective zero value)
	Recv  string // actual   receiver "T" or "*T"
	Orig  string // original receiver "T" or "*T"
	Level int    // embedding level; 0 means not embedded

	Examples []*doc.Example

	// interface type
	Field    *ast.Field
	FuncType *ast.FuncType

	// ast.FuncType fields
	Params  *ast.FieldList // (incoming) parameters; non-nil
	Results *ast.FieldList // (outgoing) results; or nil
}

Func type

func NewFuncWithDoc 

func NewFuncWithDoc(f *doc.Func) *Func

NewFuncWithDoc return func with doc.Func

type LinkWriter 

type LinkWriter func(w io.Writer, offs int, start bool)

A LinkWriter writes some start or end "tag" to w for the text offset offs. It is called by FormatSelections at the start or end of each link segment.

type Module 

type Module struct {
	Path      string       `json:",omitempty"` // module path
	Version   string       `json:",omitempty"` // module version
	Versions  []string     `json:",omitempty"` // available module versions
	Replace   *Module      `json:",omitempty"` // replaced by this module
	Time      *time.Time   `json:",omitempty"` // time version was created
	Update    *Module      `json:",omitempty"` // available update (with -u)
	Main      bool         `json:",omitempty"` // is this the main module?
	Indirect  bool         `json:",omitempty"` // module is only indirectly needed by main module
	Dir       string       `json:",omitempty"` // directory holding local copy of files, if any
	GoMod     string       `json:",omitempty"` // path to go.mod file describing module, if any
	GoVersion string       `json:",omitempty"` // go version used in module
	Error     *ModuleError `json:",omitempty"` // error loading module
}

Module go mod info type

func (*Module) String 

func (m *Module) String() string

type ModuleError 

type ModuleError struct {
	Err string // error text
}

ModuleError go mod error type

type Package 

type Package struct {
	Dir           string  // !important: directory containing package sources
	ImportPath    string  // !important: import path of package in dir
	ImportComment string  // path in import comment on package statement
	Name          string  // package name
	Doc           string  // package documentation string
	Module        *Module // info about package's module, if any
	Stale         bool    // would 'go install' do anything for this package?
	StaleReason   string  // why is Stale true?

	// declarations
	Imports   []string               // import paths used by this package
	Filenames []string               // all files
	Notes     map[string][]*doc.Note // nil if no package Notes, or contains Buts, etc...
	Consts    []*doc.Value
	Types     []*Type
	Vars      []*doc.Value
	Funcs     []*Func

	// Examples is a sorted list of examples associated with
	// the package. Examples are extracted from _test.go files provided to NewFromFiles.
	Examples []*doc.Example // nil if no example code

	ParentImportPath string     // parent package ImportPath
	Parent           *Package   `json:"-"` // parent package, important: json must ignore, prevent cycle parsing
	SubPackages      []*Package // subpackages

	Dirname string // directory containing the package
	Err     error  // error or nil

	// package info
	FSet       *token.FileSet       // nil if no package documentation
	DocPackage *doc.Package         // nil if no package documentation
	PAst       map[string]*ast.File // nil if no AST with package exports
	IsMain     bool                 // true for package main
}

Package type

func (*Package) Analyze 

func (p *Package) Analyze() (err error)

Analyze the package

func (*Package) IsEmpty 

func (p *Package) IsEmpty() bool

IsEmpty return package is empty

type PackagePublic 

type PackagePublic struct {
	Dir           string   `json:",omitempty"` // directory containing package sources
	ImportPath    string   `json:",omitempty"` // import path of package in dir
	ImportComment string   `json:",omitempty"` // path in import comment on package statement
	Name          string   `json:",omitempty"` // package name
	Doc           string   `json:",omitempty"` // package documentation string
	Target        string   `json:",omitempty"` // installed target for this package (may be executable)
	Shlib         string   `json:",omitempty"` // the shared library that contains this package (only set when -linkshared)
	Root          string   `json:",omitempty"` // Go root, Go path dir, or module root dir containing this package
	ConflictDir   string   `json:",omitempty"` // Dir is hidden by this other directory
	ForTest       string   `json:",omitempty"` // package is only for use in named test
	Export        string   `json:",omitempty"` // file containing export data (set by go list -export)
	Module        *Module  `json:",omitempty"` // info about package's module, if any
	Match         []string `json:",omitempty"` // command-line patterns matching this package
	Goroot        bool     `json:",omitempty"` // is this package found in the Go root?
	Standard      bool     `json:",omitempty"` // is this package part of the standard Go library?
	DepOnly       bool     `json:",omitempty"` // package is only as a dependency, not explicitly listed
	BinaryOnly    bool     `json:",omitempty"` // package cannot be recompiled
	Incomplete    bool     `json:",omitempty"` // was there an error loading this package or dependencies?

	// Stale and StaleReason remain here *only* for the list command.
	// They are only initialized in preparation for list execution.
	// The regular build determines staleness on the fly during action execution.
	Stale       bool   `json:",omitempty"` // would 'go install' do anything for this package?
	StaleReason string `json:",omitempty"` // why is Stale true?

	// Dependency information
	Imports   []string          `json:",omitempty"` // import paths used by this package
	ImportMap map[string]string `json:",omitempty"` // map from source import to ImportPath (identity entries omitted)
	Deps      []string          `json:",omitempty"` // all (recursively) imported dependencies

	// Test information
	// If you add to this list you MUST add to p.AllFiles (below) too.
	// Otherwise file name security lists will not apply to any new additions.
	TestGoFiles  []string `json:",omitempty"` // _test.go files in package
	TestImports  []string `json:",omitempty"` // imports from TestGoFiles
	XTestGoFiles []string `json:",omitempty"` // _test.go files outside package
	XTestImports []string `json:",omitempty"` // imports from XTestGoFiles
}

A PackagePublic describes a single package found in a directory. go/libexec/src/cmd/go/internal/load/pkg.go

type Packages 

type Packages []*Package

Packages with package array

type Page 

type Page struct {
	Corpus  *Corpus
	Package *Package
	Type    *Type
	Func    *Func

	PageType PageType

	LayoutHTML  *template.Template
	SidebarHTML *template.Template
	PackageHTML *template.Template
	TypeHTML    *template.Template
	FuncHTML    *template.Template
	FieldsHTML  *template.Template
	ExampleHTML *template.Template

	Title string

	// TabWidth optionally specifies the tab width.
	TabWidth int

	ShowPlayground bool
	DeclLinks      bool

	Sidebar []byte // Sidebar content
	Body    []byte // Main content
	// contains filtered or unexported fields
}

Page generates output from a corpus.

func NewPage 

func NewPage(c *Corpus, pkg *Package) *Page

NewPage returns a new Presentation from a corpus.

func (*Page) FuncMap 

func (page *Page) FuncMap() template.FuncMap

FuncMap defines template functions used in godoc templates.

func (*Page) Render 

func (page *Page) Render(writer io.Writer, t PageType) (err error)

Render package page

func (*Page) WriteNode 

func (page *Page) WriteNode(w io.Writer, fset *token.FileSet, x interface{})

WriteNode writes x to w. TODO(bgarcia) Is this method needed? It's just a wrapper for p.writeNode.

type PageType 

type PageType string

PageType page type 

const (
	// PackagePage package page type
	PackagePage PageType = "package"
	// TypePage type page type
	TypePage PageType = "type"
	// FuncPage func page type
	FuncPage PageType = "func"
)

type Segment 

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

A Segment describes a text segment [start, end). The zero value of a Segment is a ready-to-use empty segment.

type SegmentWriter 

type SegmentWriter func(w io.Writer, text []byte, selections int)

A SegmentWriter formats a text according to selections and writes it to w. The selections parameter is a bit set indicating which selections provided to FormatSelections overlap with the text segment: If the n'th bit is set in selections, the n'th selection provided to FormatSelections is overlapping with the text.

type Selection 

type Selection func() Segment

A Selection is an "iterator" function returning a text segment. Repeated calls to a selection return consecutive, non-overlapping, non-empty segments, followed by an infinite sequence of empty segments. The first empty segment marks the end of the selection.

func RangeSelection 

func RangeSelection(str string) Selection

RangeSelection computes the Selection for a text range described by the argument str; the range description must match the selRx regular expression.

type SpotInfo 

type SpotInfo uint32

A SpotInfo value describes a particular identifier spot in a given file; It encodes three values: the SpotKind (declaration or use), a line or snippet index "lori", and whether it's a line or index.

The following encoding is used: 

bits    32   4    1       0
value    [lori|kind|isIndex]

func (SpotInfo) IsIndex 

func (x SpotInfo) IsIndex() bool

func (SpotInfo) Kind 

func (x SpotInfo) Kind() SpotKind

func (SpotInfo) Lori 

func (x SpotInfo) Lori() int

type SpotKind 

type SpotKind uint32

SpotKind describes whether an identifier is declared (and what kind of declaration) or used. 

const (
	PackageClause SpotKind = iota
	ImportDecl
	ConstDecl
	TypeDecl
	VarDecl
	FuncDecl
	MethodDecl
	Use
)

func (SpotKind) Name 

func (x SpotKind) Name() string

type Type 

type Type struct {

	// doc.Type
	Doc  string
	Name string
	Decl *ast.GenDecl

	// associated declarations
	Consts []*doc.Value // sorted list of constants of (mostly) this type
	Vars   []*doc.Value // sorted list of variables of (mostly) this type

	Funcs   []*Func // sorted list of functions returning this type
	Methods []*Func // sorted list of methods (including embedded ones) of this type

	// Examples is a sorted list of examples associated with
	// this type. Examples are extracted from _test.go files
	// provided to NewFromFiles.
	Examples []*doc.Example

	Fields *ast.FieldList
}

Type type

func NewTypeWithDoc 

func NewTypeWithDoc(t *doc.Type) *Type

NewTypeWithDoc return type with doc.Type

Notes

Bugs

  • test bug info.

Source Files

View all Source files

Directories

Path Synopsis
cmd
gsd
testpkg

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.