-
Notifications
You must be signed in to change notification settings - Fork 7
/
documentation.go
103 lines (103 loc) · 4.13 KB
/
documentation.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
// Automatically generate a github README.md for each package in your Go module.
//
// # Examples
//
// Create a README.md for each package in the current module (Warning: this will overwrite any existing README.md files!)
//
// autoreadme
//
// Get a copy of the default template for customization
//
// autoreadme -print-template >README.md.template
//
// # Template Variables
//
// Templates are executed by Go's text/template. The dot is set to a struct containing (each explained below)
//
// .ProjectRoot
// .Repository
// .Module
// .Package
//
// ProjectRoot is a boolean which is true if the current package is in the same directory as go.mod.
//
// The Repository entry consists solely of .Data, which may contain optional arbitrary data
// set by JSON in .github/autoreadme/README.md.data.
//
// The Module entry contains:
//
// .Path - the name of the module
// .Version - the version of the module
// .Deprecated - deprecation notice, if present
// .GoVersion - the language version of the module
// .Toolchain - the toolchain version of the module
// .Documentation - a Documentation entry (see below)
//
// The Package entry contains:
//
// .Name
// .Import - the import path of the package
// .Documentation - a Documentation entry (see below)
// .Data - optional arbitrary data set by a JSON in ./README.md.data
// .Library - true if not a command
// .Command - true if package main
// .Notes - a list of Note (see below) entries
// .Examples - a list of Example (see below) entries
// .ExternalExamples - like Examples but for examples from package X_test
//
// Name is the package name for libraries. However, for commands that is always "main"
// so for commands it uses the name of the directory.
//
// Documentation entries contain
//
// .Synopsis - The first sentence as plain text
// .Doc - the raw go/doc/comment/Doc
// .Empty - false if there is documentation
//
// additionally Documentation has a
//
// .ToMarkdown headingLevel
//
// method that renders .Doc as markdown.
// Each heading in Doc is set to headingLevel, allowing them to be properly nested in context.
//
// For packages, the documentation is computed in the standard way by comments attached to the package token.
// For modules, similar logic is used for the comments attached to the module token (note: any Deprecated: comment is not included, but can be accessed from .Module.Deprecated).
//
// Example entries contain
//
// .Name - func Name without Example prefix
// .Documentation - Doc entry for the example func
// .Code - markdown formatted code
// .Output - the expected output, if specified
// .Playable - if the example is self-contained
// .Unordered - if the output is unordered
// .EmptyOutput - if the expected result is no output
//
// and the lists of examples have a few methods
// 1. Playable - returns a list where Playable is true
// 2. Named name - returns the single Example with that exact name or halts execution if there is none
// 3. Matching pattern - returns all examples whose name matches the RE2 regexp pattern
//
// Note entries collect the "KIND(uid): body" notes from the package (per go/doc)
//
// .Kind - the kind of note
// .UID - the name associated with this name
// .Body - the text of the note
//
// The list of notes has two methods, Kind and UID, which take a string
// and return a list of notes matching the respective Kind/UID.
//
// # Repository Configuration
//
// A number of files can be added to a .github/autoreadme directory at the root of your repository.
// 1. .github/autoreadme/README.md.template will override the built in default template for all packages without their own template
// 2. .github/autoreadme/README.md.data can contain a single JSON document that can be accessed by every template using .Repository.Data
// 3. .github/autoreadme/autoreadme.ignore can contain a newline separated list of import paths that will be skipped when README.md are generated
//
// # Package configuration
//
// Two files can be added to the directory of each package for one-off customizations
// 1. README.md.template will override the default (or repository) template
// 2. README.md.data can contain a single JSON document that can be accessed by .Package.Data
package main