Imports #
"fmt"
"strings"
md "rsc.io/markdown"
"fmt"
"strings"
"unicode"
"unicode/utf8"
"golang.org/x/mod/module"
md "rsc.io/markdown"
"bufio"
"bytes"
"errors"
"fmt"
"io"
"io/fs"
"path"
"regexp"
"slices"
"strconv"
"strings"
md "rsc.io/markdown"
relnote
Imports
Constants & Variables
apiFileLineRegexp var #
This regexp has four capturing groups: package, build, feature and issue.
var apiFileLineRegexp = *ast.CallExprStructs
APIFeature struct #
An APIFeature is a symbol mentioned in an API file, like the ones in the main go repo in the api directory.
type APIFeature struct {
Package string
Build string
Feature string
Issue int
}Functions
CheckAPIFile function #
CheckAPIFile reads the api file at filename in apiFS, and checks the corresponding release-note files under docFS. It checks that the files exist and that they have some minimal content (see [CheckFragment]). The docRoot argument is the path from the repo or project root to the root of docFS. It is used only for error messages.
func CheckAPIFile(apiFS fs.FS, filename string, docFS fs.FS, docRoot string) errorCheckFragment function #
CheckFragment reports problems in a release-note fragment.
func CheckFragment(data string) errorDumpMarkdown function #
DumpMarkdown writes the internal structure of a markdown document to standard output. It is intended for debugging.
func DumpMarkdown(d *md.Document)GroupAPIFeaturesByFile function #
GroupAPIFeaturesByFile returns a map of the given features keyed by the doc filename that they are associated with. A feature with package P and issue N should be documented in the file "P/N.md".
func GroupAPIFeaturesByFile(fs []APIFeature) (map[string][]APIFeature, error)Merge function #
Merge combines the markdown documents (files ending in ".md") in the tree rooted at fs into a single document. The blocks of the documents are concatenated in lexicographic order by filename. Heading with no content are removed. The link keys must be unique, and are combined into a single map. Files in the "minor changes" directory (the unique directory matching the glob "*stdlib/*minor") are named after the package to which they refer, and will have the package heading inserted automatically and links to other standard library symbols expanded automatically. For example, if a file *stdlib/minor/bytes/f.md contains the text [Reader] implements [io.Reader]. then that will become [Reader](/pkg/bytes#Reader) implements [io.Reader](/pkg/io#Reader).
func Merge(fsys fs.FS) (*md.Document, error)NewParser function #
NewParser returns a properly configured Markdown parser.
func NewParser() *md.ParseraddLines function #
addLines adds n lines to the position of b. n can be negative.
func addLines(b md.Block, n int)addSymbolLinks function #
addSymbolLinks looks for text like [Buffer] and [math.Max] and replaces them with links to standard library symbols and packages. It uses the given default package for links without a package.
func addSymbolLinks(doc *md.Document, defaultPackage string)addSymbolLinksBlock function #
func addSymbolLinksBlock(b md.Block, defaultPackage string)addSymbolLinksBlocks function #
func addSymbolLinksBlocks(bs []md.Block, defaultPackage string)addSymbolLinksInlines function #
addSymbolLinksInlines looks for symbol links in the slice of inline markdown elements. It returns a new slice of inline elements with links added.
func addSymbolLinksInlines(ins []md.Inline, defaultPackage string) []md.InlineblocksText function #
blocksText returns all the text in a slice of block nodes.
func blocksText(bs []md.Block) stringcheckFragmentFile function #
func checkFragmentFile(fsys fs.FS, filename string) errordprintf function #
func dprintf(depth int, format string, args ...any)dumpBlock function #
func dumpBlock(b md.Block, depth int)dumpBlocks function #
func dumpBlocks(bs []md.Block, depth int)dumpInlines function #
func dumpInlines(ins []md.Inline, depth int)ident function #
ident checks whether s begins with a Go identifier. If so, it returns the identifier, which is a prefix of s, and ok == true. Otherwise it returns "", false. The caller should skip over the first len(id) bytes of s before further processing.
func ident(s string) (id string, ok bool)inlineText function #
inlineText returns all the next in a slice of inline nodes.
func inlineText(ins []md.Inline) stringisIdentASCII function #
isIdentASCII reports whether c is an ASCII identifier byte.
func isIdentASCII(c byte) boolisLinkAdjacentRune function #
isLinkAdjacentRune reports whether r can be adjacent to a symbol link. The logic is the same as the go/doc/comment package.
func isLinkAdjacentRune(r rune) boolisName function #
isName reports whether s is a capitalized Go identifier (like Name).
func isName(s string) boollastBlock function #
lastBlock returns the last block in the document. It panics if the document has no blocks.
func lastBlock(doc *md.Document) md.BlockminorChangesDir function #
minorChangesDir returns the unique directory in docFS that corresponds to the "Minor changes to the standard library" section of the release notes.
func minorChangesDir(docFS fs.FS) (string, error)parseAPIFile function #
parseAPIFile parses a file in the api format and returns a list of the file's features. A feature is represented by a single line that looks like pkg PKG (BUILD) FEATURE #ISSUE where the BUILD and ISSUE may be absent.
func parseAPIFile(fsys fs.FS, filename string) ([]APIFeature, error)parseMarkdownFile function #
func parseMarkdownFile(fsys fs.FS, path string) (*md.Document, error)position function #
func position(b md.Block) *md.PositionremoveEmptySections function #
removeEmptySections removes headings with no content. A heading has no content if there are no blocks between it and the next heading at the same level, or the end of the document.
func removeEmptySections(bs []md.Block) []md.BlocksortedMarkdownFilenames function #
func sortedMarkdownFilenames(fsys fs.FS) ([]string, error)splitAtBrackets function #
splitAtBrackets rewrites ins so that every '[' and ']' is the only character of its Plain. For example, the element [Plain("the [Buffer] is")] is rewritten to [Plain("the "), Plain("["), Plain("Buffer"), Plain("]"), Plain(" is")] This transformation simplifies looking for symbol links.
func splitAtBrackets(ins []md.Inline) []md.InlinesplitDocName function #
If text is of the form before.Name, where Name is a capitalized Go identifier, then splitDocName returns before, name, true. Otherwise it returns text, "", false.
func splitDocName(text string) (before string, name string, foundDot bool)splitRef function #
splitRef splits s into a package and possibly a symbol. Examples: splitRef("math.Max") => ("math", "Max", true) splitRef("bytes.Buffer.String") => ("bytes", "Buffer.String", true) splitRef("math") => ("math", "", true)
func splitRef(s string) (pkg string, name string, ok bool)stdlibPackage function #
stdlibPackage returns the standard library package for the given filename. If the filename does not represent a package, it returns the empty string. A filename represents package P if it is in a directory matching the glob "*stdlib/*minor/P".
func stdlibPackage(filename string) stringstdlibPackageHeading function #
func stdlibPackageHeading(pkg string, lastLine int) *md.HeadingsymbolLink function #
symbolLink converts s into a Link and returns it and true, or nil and false if s is not a valid link or is surrounded by runes that disqualify it from being converted to a link. The argument s is the text between '[' and ']'.
func symbolLink(s string, defaultPackage string) (md.Inline, bool)symbolLinkText function #
symbolLinkText returns the text of a possible symbol link. It is given a slice of Inline elements and an index into the slice. If the index refers to a sequence of elements [Plain("["), Plain_or_Code(text), Plain("]")] and the brackets are adjacent to the right kind of runes for a link, then symbolLinkText returns the text of the middle element. Otherwise it returns the empty string.
func symbolLinkText(i int, ins []md.Inline) stringtext function #
text returns all the text in a block, without any formatting.
func text(b md.Block) stringGenerated with Arrow