feat: make it easier to customize package imports

princjef · princjef · commit 80124ce84a76 · 2022-07-06T23:33:24.000-07:00
diff --git a/README.md b/README.md
@@ -118,6 +118,8 @@ The documentation information that is output is formatted using a series of text
 
 - doc:     generates the freeform documentation block for any of the above
            structures that can contain a documentation section.
+
+- import:  generates the import code used to pull in a package.
 ```
 
 Overriding with the \-t option uses a key\-vaule pair mapping a template name to the file containing the contents of the override template to use\. Specified template files must exist:
diff --git a/doc.go b/doc.go
@@ -125,6 +125,8 @@
 //	- doc:     generates the freeform documentation block for any of the above
 //	           structures that can contain a documentation section.
 //
+//	- import:  generates the import code used to pull in a package.
+//
 // Overriding with the -t option uses a key-vaule pair mapping a template name
 // to the file containing the contents of the override template to use.
 // Specified template files must exist:
diff --git a/lang/README.md b/lang/README.md
@@ -61,6 +61,7 @@ Package lang provides constructs for defining golang language constructs and ext
   - [func (pkg *Package) Examples() (examples []*Example)](<#func-package-examples>)
   - [func (pkg *Package) Funcs() (funcs []*Func)](<#func-package-funcs>)
   - [func (pkg *Package) Import() string](<#func-package-import>)
+  - [func (pkg *Package) ImportPath() string](<#func-package-importpath>)
   - [func (pkg *Package) Level() int](<#func-package-level>)
   - [func (pkg *Package) Name() string](<#func-package-name>)
   - [func (pkg *Package) Summary() string](<#func-package-summary>)
@@ -487,7 +488,7 @@ func NewPackageFromBuild(log logger.Logger, pkg *build.Package, opts ...PackageO
 
 NewPackageFromBuild creates a representation of a package's documentation from the build metadata for that package\. It can be configured using the provided options\.
 
-### func \(\*Package\) [Consts](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L149>)
+### func \(\*Package\) [Consts](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L156>)
 
 ```go
 func (pkg *Package) Consts() (consts []*Value)
@@ -511,23 +512,23 @@ func (pkg *Package) Dirname() string
 
 Dirname provides the name of the leaf directory in which the package is located\.
 
-### func \(\*Package\) [Doc](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L143>)
+### func \(\*Package\) [Doc](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L150>)
 
 ```go
 func (pkg *Package) Doc() *Doc
 ```
 
 Doc provides the structured contents of the documentation comment for the package\.
 
-### func \(\*Package\) [Examples](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L187>)
+### func \(\*Package\) [Examples](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L194>)
 
 ```go
 func (pkg *Package) Examples() (examples []*Example)
 ```
 
 Examples provides the package\-level examples that have been defined\. This does not include examples that are associated with symbols contained within the package\.
 
-### func \(\*Package\) [Funcs](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L167>)
+### func \(\*Package\) [Funcs](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L174>)
 
 ```go
 func (pkg *Package) Funcs() (funcs []*Func)
@@ -543,6 +544,14 @@ func (pkg *Package) Import() string
 
 Import provides the raw text for the import declaration that is used to import code from the package\. If your package's documentation is generated from a local path and does not use Go Modules\, this will typically print \`import "\."\`\.
 
+### func \(\*Package\) [ImportPath](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L138>)
+
+```go
+func (pkg *Package) ImportPath() string
+```
+
+ImportPath provides the identifier used for the package when installing or importing the package\. If your package's documentation is generated from a local path and does not use Go Modules\, this will typically print \`\.\`\.
+
 ### func \(\*Package\) [Level](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L106>)
 
 ```go
@@ -559,23 +568,23 @@ func (pkg *Package) Name() string
 
 Name provides the name of the package as it would be seen from another package importing it\.
 
-### func \(\*Package\) [Summary](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L137>)
+### func \(\*Package\) [Summary](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L144>)
 
 ```go
 func (pkg *Package) Summary() string
 ```
 
 Summary provides the one\-sentence summary of the package's documentation comment\.
 
-### func \(\*Package\) [Types](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L176>)
+### func \(\*Package\) [Types](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L183>)
 
 ```go
 func (pkg *Package) Types() (types []*Type)
 ```
 
 Types lists the top\-level types provided by the package\.
 
-### func \(\*Package\) [Vars](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L158>)
+### func \(\*Package\) [Vars](<https://github.com/princjef/gomarkdoc/blob/master/lang/package.go#L165>)
 
 ```go
 func (pkg *Package) Vars() (vars []*Value)
diff --git a/lang/package.go b/lang/package.go
@@ -132,6 +132,13 @@ func (pkg *Package) Import() string {
 	return fmt.Sprintf(`import "%s"`, pkg.doc.ImportPath)
 }
 
+// ImportPath provides the identifier used for the package when installing or
+// importing the package. If your package's documentation is generated from a
+// local path and does not use Go Modules, this will typically print `.`.
+func (pkg *Package) ImportPath() string {
+	return pkg.doc.ImportPath
+}
+
 // Summary provides the one-sentence summary of the package's documentation
 // comment.
 func (pkg *Package) Summary() string {
diff --git a/lang/package_test.go b/lang/package_test.go
@@ -57,6 +57,7 @@ func TestPackage_dotImport(t *testing.T) {
 	is.NoErr(err)
 
 	is.Equal(pkg.Import(), `import "github.com/princjef/gomarkdoc/testData/lang/function"`)
+	is.Equal(pkg.ImportPath(), `github.com/princjef/gomarkdoc/testData/lang/function`)
 }
 
 func TestPackage_strings(t *testing.T) {
@@ -74,6 +75,7 @@ func TestPackage_strings(t *testing.T) {
 	is.Equal(pkg.Dirname(), "strings")
 	is.Equal(pkg.Name(), "strings")
 	is.Equal(pkg.Import(), `import "strings"`)
+	is.Equal(pkg.ImportPath(), `strings`)
 	is.Equal(pkg.Summary(), "Package strings implements simple functions to manipulate UTF-8 encoded strings.")
 	is.Equal(len(pkg.Consts()), 0)   // strings should have no constants
 	is.Equal(len(pkg.Vars()), 0)     // strings should have no vars
@@ -97,6 +99,7 @@ func TestPackage_textScanner(t *testing.T) {
 	is.Equal(pkg.Dirname(), "scanner")
 	is.Equal(pkg.Name(), "scanner")
 	is.Equal(pkg.Import(), `import "text/scanner"`)
+	is.Equal(pkg.ImportPath(), `text/scanner`)
 	is.Equal(pkg.Summary(), "Package scanner provides a scanner and tokenizer for UTF-8-encoded text.")
 	is.True(len(pkg.Consts()) > 0)   // text/scanner should have constants
 	is.Equal(len(pkg.Vars()), 0)     // text/scanner should have no vars
@@ -120,6 +123,7 @@ func TestPackage_ioIoutil(t *testing.T) {
 	is.Equal(pkg.Dirname(), "ioutil")
 	is.Equal(pkg.Name(), "ioutil")
 	is.Equal(pkg.Import(), `import "io/ioutil"`)
+	is.Equal(pkg.ImportPath(), `io/ioutil`)
 	is.Equal(pkg.Summary(), "Package ioutil implements some I/O utility functions.")
 	is.Equal(len(pkg.Consts()), 0)   // io/ioutil should have no constants
 	is.True(len(pkg.Vars()) > 0)     // io/ioutil should have vars
@@ -143,6 +147,7 @@ func TestPackage_encoding(t *testing.T) {
 	is.Equal(pkg.Dirname(), "encoding")
 	is.Equal(pkg.Name(), "encoding")
 	is.Equal(pkg.Import(), `import "encoding"`)
+	is.Equal(pkg.ImportPath(), `encoding`)
 	is.Equal(pkg.Summary(), "Package encoding defines interfaces shared by other packages that convert data to and from byte-level and textual representations.")
 	is.Equal(len(pkg.Consts()), 0)   // encoding should have no constants
 	is.Equal(len(pkg.Vars()), 0)     // encoding should have no vars
diff --git a/templates.go b/templates.go
diff --git a/templates/import.gotxt b/templates/import.gotxt
@@ -0,0 +1,2 @@
+{{- codeBlock "go" .Import -}}
+
diff --git a/templates/package.gotxt b/templates/package.gotxt
@@ -4,7 +4,7 @@
 	{{- header .Level .Name -}}
 {{- end -}}
 
-{{- codeBlock "go" .Import -}}
+{{- template "import" . -}}
 
 {{- template "doc" .Doc -}}
 
