forked from jimmyfrasche/autoreadme
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathϟdocϟ.go
156 lines (154 loc) · 6.12 KB
/
ϟdocϟ.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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
// Copyright 2013 James Frasche. All rights reserved.
// Copyright 2021 John Papandriopoulos.
// Use of this code is governed by a BSD-License found in the LICENSE file.
// Automatically generate a Markdown README for your Go project.
//
// This tool creates a GitHub-flavored README.md using the same format as godoc.
// It includes the package summary and generates badges for pkg.go.dev and
// Travis CI.
//
// This is a fork of James Frasche's project, found at
// https://github.com/jimmyfrasche/autoreadme.
//
//
// What It Does
//
// By default, `godoc-readme-gen` will read the Go package in the working
// directory, and generate a `README.md` file. If the README already exists, it
// will not be overwritten without the `-f` flag. You can specify the path to
// the package directory as the final argument to the tool.
//
// A template for the README is specified by the `-template` flag, and by
// default it looks for a file named `.README.template.md` in the package
// directory. If the default template is not found, or an alternate is not
// provided, the default template is used.
//
// To view the default template, pass the `-print-template` function to dump it
// to stdout. You might redirect this output to a file so you may use it as the
// basis for creating your own custom template.
//
//
// Lists and Bullets
//
// Paragraphs that start with the text "1. ", "2. ", etc. are automatically
// turned into lists by Markdown. Paragraphs between list items are
// automatically indented so that they appear as part of the same list item.
// Similarly for bullets, that are paragraphs that start with the text "* ".
//
// We assume the list and/or bullets continue until the end of the text section
// (that is, until the next heading or end of document). But sometimes you may
// wish to "terminate" a list/bullet before then: to do this, insert a pseudo
// heading "..." before the next paragraph. The ellipses will not be inserted
// into the README file.
//
// The following example illustrates this concept:
//
// // Example List
// //
// // 1. Apple
// //
// // An Apple a day keeps the doctor away.
// //
// // 2. Pear
// //
// // Not to be confused with "pair".
// //
// // ...
// //
// // This trailing paragraph is not indented, as it is not considered to be
// // part of the above list.
//
//
// Automating README Generation
//
// To track changes in your godoc, and ensure that your README is always kept up
// to date, we recommend adding a `//go:generate` line to your Go package so
// that you can easily re-generate the README via the `go generate` command-line
// tool.
//
// If you have one or more sub-packages in your project, you can add similar
// `//go:generate` lines to each, and then regenerate all of the READMEs by
// running `go generate ./...` from the top-level directory.
//
// We recommend placing your high-level godoc comments in a separate project
// file `ϟdocϟ.go` and a `//go:generate` line beneath the `package` declaration
// as follows:
//
// // Package demo shows how you might structure a "ϟdocϟ.go" file.
// package demo // import "corp.example.com/demo"
//
// //go:generate godoc-readme-gen -f -title "Demo Usage of godoc-read-me-gen"
// // To install: `go install go.jpap.org/godoc-readme-gen`
//
// Naming this file with the given Unicode "ϟ" character ensures `go generate`
// generates your README **last**, because it processes files in sorted order.
// This is important because `godoc-readme-gen` requires your Go project to
// build without error (so it can parse the source code). If other generators
// have not yet run, or require regeneration (e.g. out-of-date `stringer`
// files), your source code might not "compile" and `godoc-readme-gen` will
// fail, stopping `go generate` from running the other generators.
//
// Unfortunately Go source filenames are restricted to being ASCII or Unicode
// letters, and limited to ASCII punctuation when using modules. The allowed
// punctuation characters "compare before" all of the ASCII letters, so we are
// then forced to use a Unicode letter that always "compares after" all of the
// ASCII letters. We choose the ancient Greek letter koppa "ϟ" for this
// purpose, because it "compares after" all Greek characters too!
//
//
// Examples
//
// Create a README.md for the package in directory a/b/c, with `.Title` template
// variable set to "A Great Package":
// godoc-readme-gen -title "A Great Package" a/b/c
//
// Overwrite the README.md in the current directory:
// godoc-readme-gen -f
//
// Copy the built-in template to a file for the creation of a new template:
// godoc-readme-gen -print-template > .README.template.md
//
// Generate using a custom template:
// godoc-readme-gen -template path/to/my/readme.template.md
//
//
// Template Variables
//
// The following variables are available in custom templates:
//
// `.Name` Package name.
//
// `.Title` The -title flag value, or package name if not provided.
//
// `.Doc` Package-level documentation.
//
// `.Synopsis` The first sentence from the .Doc variable.
//
// `.ImportPath` Package import path.
//
// `.RepoPath` The import path without the first path component. For example,
// the import github.com/golang/go is represented as "golang/go". This is
// typically the path within the repo of the package.
//
// `.Bugs` A []string of all bugs as per godoc.
//
// `.Commands` A []string of import paths of all main packages. In addition to
// the directory provided to the tool, we also check cmd/* directories for
// additional main packages.
//
// `.Library` True if the package is not a main package.
//
// `.Today` The current date in YYYY.MM.DD format.
//
// `.Travis` True if there is a `.travis.yml` file in the package directory.
//
// `.Examples` a map of Example with all examples from `*_test.go` files. These
// can be used to include selective examples into the README. The Example
// struct has the following fields:
// .Name Name of the example
// .Code Rendered example code similar to godoc
// .Output Example output, if any
//
package main
//go:generate godoc-readme-gen -f -title "GoDoc README Markdown Generator"
// To install: `go install go.jpap.org/godoc-readme-gen`