Skip to content

Commit cc78abb

Browse files
princjefprincjef
authored
feat: add support for links in documentation (#89)
1 parent 7d0c2ca commit cc78abb

38 files changed

+1516
-478
lines changed

‎README.md‎

Lines changed: 29 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
import "github.com/princjef/gomarkdoc"
1212
```
1313

14-
Package gomarkdoc formats documentation for one or more packages as markdown for usage outside of the main https://pkg.go.dev site. It supports custom templates for tweaking representation of documentation at fine\-grained levels, exporting both exported and unexported symbols, and custom formatters for different backends.
14+
Package gomarkdoc formats documentation for one or more packages as markdown for usage outside of the main https://pkg.go.dev[https://pkg.go.dev](<https://pkg.go.dev>) site. It supports custom templates for tweaking representation of documentation at fine\-grained levels, exporting both exported and unexported symbols, and custom formatters for different backends.
1515

1616
### Command Line Usage
1717

@@ -100,7 +100,7 @@ The documentation information that is output is formatted using a series of text
100100

101101
- index: generates an index of symbols within a package, similar to what is seen for godoc.org. The index links to types, funcs, variables, and constants generated by other templates, so it may need to be overridden as well if any of those templates are changed in a material way.
102102

103-
- example: generates documentation for a single example for a package or one of its symbols. The example is generated alongside whichever symbol it represents, based on the standard naming conventions outlined in https://blog.golang.org/examples#TOC_4 .
103+
- example: generates documentation for a single example for a package or one of its symbols. The example is generated alongside whichever symbol it represents, based on the standard naming conventions outlined in https://blog.golang.org/examples#TOC_4[https://blog.golang.org/examples#TOC_4](<https://blog.golang.org/examples#TOC_4>).
104104

105105
- doc: generates the freeform documentation block for any of the above structures that can contain a documentation section.
106106

@@ -229,18 +229,19 @@ Know of another project that is using gomarkdoc? Open an issue with a descriptio
229229

230230
## Index
231231

232-
- [type Renderer](<#type-renderer>)
233-
- [func NewRenderer(opts ...RendererOption) (*Renderer, error)](<#func-newrenderer>)
234-
- [func (out *Renderer) Example(ex *lang.Example) (string, error)](<#func-renderer-example>)
235-
- [func (out *Renderer) File(file *lang.File) (string, error)](<#func-renderer-file>)
236-
- [func (out *Renderer) Func(fn *lang.Func) (string, error)](<#func-renderer-func>)
237-
- [func (out *Renderer) Package(pkg *lang.Package) (string, error)](<#func-renderer-package>)
238-
- [func (out *Renderer) Type(typ *lang.Type) (string, error)](<#func-renderer-type>)
239-
- [type RendererOption](<#type-rendereroption>)
240-
- [func WithFormat(format format.Format) RendererOption](<#func-withformat>)
241-
- [func WithTemplateOverride(name, tmpl string) RendererOption](<#func-withtemplateoverride>)
232+
- [type Renderer](<#Renderer>)
233+
- [func NewRenderer(opts ...RendererOption) (*Renderer, error)](<#NewRenderer>)
234+
- [func (out *Renderer) Example(ex *lang.Example) (string, error)](<#Renderer.Example>)
235+
- [func (out *Renderer) File(file *lang.File) (string, error)](<#Renderer.File>)
236+
- [func (out *Renderer) Func(fn *lang.Func) (string, error)](<#Renderer.Func>)
237+
- [func (out *Renderer) Package(pkg *lang.Package) (string, error)](<#Renderer.Package>)
238+
- [func (out *Renderer) Type(typ *lang.Type) (string, error)](<#Renderer.Type>)
239+
- [type RendererOption](<#RendererOption>)
240+
- [func WithFormat(format format.Format) RendererOption](<#WithFormat>)
241+
- [func WithTemplateOverride(name, tmpl string) RendererOption](<#WithTemplateOverride>)
242242

243243

244+
<a name="Renderer"></a>
244245
## type [Renderer](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L16-L20>)
245246

246247
Renderer provides capabilities for rendering various types of documentation with the configured format and templates.
@@ -251,6 +252,7 @@ type Renderer struct {
251252
}
252253
```
253254

255+
<a name="NewRenderer"></a>
254256
### func [NewRenderer](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L31>)
255257

256258
```go
@@ -259,46 +261,52 @@ func NewRenderer(opts ...RendererOption) (*Renderer, error)
259261

260262
NewRenderer initializes a Renderer configured using the provided options. If nothing special is provided, the created renderer will use the default set of templates and the GitHubFlavoredMarkdown.
261263

262-
### func \(\*Renderer\) [Example](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L181>)
264+
<a name="Renderer.Example"></a>
265+
### func \(\*Renderer\) [Example](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L184>)
263266

264267
```go
265268
func (out *Renderer) Example(ex *lang.Example) (string, error)
266269
```
267270

268271
Example renders an example's documentation to a string. You can change the rendering of the example by overriding the "example" template or one of the templates it references.
269272

270-
### func \(\*Renderer\) [File](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L153>)
273+
<a name="Renderer.File"></a>
274+
### func \(\*Renderer\) [File](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L156>)
271275

272276
```go
273277
func (out *Renderer) File(file *lang.File) (string, error)
274278
```
275279

276280
File renders a file containing one or more packages to document to a string. You can change the rendering of the file by overriding the "file" template or one of the templates it references.
277281

278-
### func \(\*Renderer\) [Func](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L167>)
282+
<a name="Renderer.Func"></a>
283+
### func \(\*Renderer\) [Func](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L170>)
279284

280285
```go
281286
func (out *Renderer) Func(fn *lang.Func) (string, error)
282287
```
283288

284289
Func renders a function's documentation to a string. You can change the rendering of the package by overriding the "func" template or one of the templates it references.
285290

286-
### func \(\*Renderer\) [Package](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L160>)
291+
<a name="Renderer.Package"></a>
292+
### func \(\*Renderer\) [Package](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L163>)
287293

288294
```go
289295
func (out *Renderer) Package(pkg *lang.Package) (string, error)
290296
```
291297

292298
Package renders a package's documentation to a string. You can change the rendering of the package by overriding the "package" template or one of the templates it references.
293299

294-
### func \(\*Renderer\) [Type](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L174>)
300+
<a name="Renderer.Type"></a>
301+
### func \(\*Renderer\) [Type](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L177>)
295302

296303
```go
297304
func (out *Renderer) Type(typ *lang.Type) (string, error)
298305
```
299306

300307
Type renders a type's documentation to a string. You can change the rendering of the type by overriding the "type" template or one of the templates it references.
301308

309+
<a name="RendererOption"></a>
302310
## type [RendererOption](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L23>)
303311

304312
RendererOption configures the renderer's behavior.
@@ -307,15 +315,17 @@ RendererOption configures the renderer's behavior.
307315
type RendererOption func(renderer *Renderer) error
308316
```
309317

310-
### func [WithFormat](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L143>)
318+
<a name="WithFormat"></a>
319+
### func [WithFormat](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L146>)
311320

312321
```go
313322
func WithFormat(format format.Format) RendererOption
314323
```
315324

316325
WithFormat changes the renderer to use the format provided instead of the default format.
317326

318-
### func [WithTemplateOverride](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L129>)
327+
<a name="WithTemplateOverride"></a>
328+
### func [WithTemplateOverride](<https://github.com/princjef/gomarkdoc/blob/master/renderer.go#L132>)
319329

320330
```go
321331
func WithTemplateOverride(name, tmpl string) RendererOption

‎cmd/gomarkdoc/README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,14 @@ import "github.com/princjef/gomarkdoc/cmd/gomarkdoc"
88

99
Package gomarkdoc provides a command line interface for writing golang documentation in markdown format.
1010

11-
See https://github.com/princjef/gomarkdoc for full documentation of this tool.
11+
See https://github.com/princjef/gomarkdoc[https://github.com/princjef/gomarkdoc](<https://github.com/princjef/gomarkdoc>) for full documentation of this tool.
1212

1313
## Index
1414

15-
- [type PackageSpec](<#type-packagespec>)
15+
- [type PackageSpec](<#PackageSpec>)
1616

1717

18+
<a name="PackageSpec"></a>
1819
## type [PackageSpec](<https://github.com/princjef/gomarkdoc/blob/master/cmd/gomarkdoc/command.go#L30-L44>)
1920

2021
PackageSpec defines the data available to the \-\-output option's template. Information is recomputed for each package generated.

0 commit comments

Comments
 (0)