diff options
author | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2022-12-30 09:20:58 +0100 |
---|---|---|
committer | Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com> | 2023-01-04 18:01:26 +0100 |
commit | e402d91ee199afcace8ae75da6c3587bb8089ace (patch) | |
tree | a0f51de9707ed03aa1a3d7a9195fd9d0fceab108 /resources | |
parent | 3c51625c7152abca7e035fae15fc6807ca21cc86 (diff) |
Misc doc, code refactoring to improve documentation
Diffstat (limited to 'resources')
-rw-r--r-- | resources/docs.go | 15 | ||||
-rw-r--r-- | resources/images/exif/exif.go | 3 | ||||
-rw-r--r-- | resources/images/image_resource.go | 10 | ||||
-rw-r--r-- | resources/page/page.go | 41 | ||||
-rw-r--r-- | resources/page/page_marshaljson.autogen.go | 13 | ||||
-rw-r--r-- | resources/page/page_nop.go | 5 | ||||
-rw-r--r-- | resources/page/pagination.go | 4 | ||||
-rw-r--r-- | resources/page/site.go | 7 | ||||
-rw-r--r-- | resources/page/taxonomy.go | 168 | ||||
-rw-r--r-- | resources/page/testhelpers_test.go | 5 | ||||
-rw-r--r-- | resources/resource/resources.go | 3 | ||||
-rw-r--r-- | resources/resource/resourcetypes.go | 3 |
12 files changed, 253 insertions, 24 deletions
diff --git a/resources/docs.go b/resources/docs.go new file mode 100644 index 000000000..f992893da --- /dev/null +++ b/resources/docs.go @@ -0,0 +1,15 @@ +// Copyright 2023 The Hugo Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +// Package resources contains Resource related types. +package resources diff --git a/resources/images/exif/exif.go b/resources/images/exif/exif.go index 487f250d5..8df348b23 100644 --- a/resources/images/exif/exif.go +++ b/resources/images/exif/exif.go @@ -254,8 +254,10 @@ func init() { } } +// Tags is a map of EXIF tags. type Tags map[string]any +// UnmarshalJSON is for internal use only. func (v *Tags) UnmarshalJSON(b []byte) error { vv := make(map[string]any) if err := tcodec.Unmarshal(b, &vv); err != nil { @@ -267,6 +269,7 @@ func (v *Tags) UnmarshalJSON(b []byte) error { return nil } +// MarshalJSON is for internal use only. func (v Tags) MarshalJSON() ([]byte, error) { return tcodec.Marshal(v) } diff --git a/resources/images/image_resource.go b/resources/images/image_resource.go index 4e66b010c..846959006 100644 --- a/resources/images/image_resource.go +++ b/resources/images/image_resource.go @@ -29,6 +29,7 @@ type ImageResource interface { type ImageResourceOps interface { // Height returns the height of the Image. Height() int + // Width returns the width of the Image. Width() int @@ -37,8 +38,17 @@ type ImageResourceOps interface { // Use the anchor option to change the crop box anchor point. // {{ $image := $image.Crop "600x400" }} Crop(spec string) (ImageResource, error) + + // Fill scales the image to the smallest possible size that will cover the specified dimensions in spec, + // crops the resized image to the specified dimensions using the given anchor point. + // The spec is space delimited, e.g. `200x300 TopLeft`. Fill(spec string) (ImageResource, error) + + // Fit scales down the image using the given spec. Fit(spec string) (ImageResource, error) + + // Resize resizes the image to the given spec. If one of width or height is 0, the image aspect + // ratio is preserved. Resize(spec string) (ImageResource, error) // Filter applies one or more filters to an Image. diff --git a/resources/page/page.go b/resources/page/page.go index 929f04d93..eeb2cdb28 100644 --- a/resources/page/page.go +++ b/resources/page/page.go @@ -21,7 +21,6 @@ import ( "github.com/gohugoio/hugo/identity" "github.com/gohugoio/hugo/markup/converter" - "github.com/bep/gitmap" "github.com/gohugoio/hugo/config" "github.com/gohugoio/hugo/tpl" @@ -61,18 +60,17 @@ type AuthorProvider interface { // ChildCareProvider provides accessors to child resources. type ChildCareProvider interface { + // Pages returns a list of pages of all kinds. Pages() Pages // RegularPages returns a list of pages of kind 'Page'. - // In Hugo 0.57 we changed the Pages method so it returns all page - // kinds, even sections. If you want the old behaviour, you can - // use RegularPages. RegularPages() Pages // RegularPagesRecursive returns all regular pages below the current // section. RegularPagesRecursive() Pages + // Resources returns a list of all resources. Resources() resource.Resources } @@ -103,16 +101,21 @@ type ContentProvider interface { ReadingTime() int // Len returns the length of the content. + // This is for internal use only. Len() int } // ContentRenderer provides the content rendering methods for some content. type ContentRenderer interface { + // RenderContent renders the given content. + // For internal use only. RenderContent(content []byte, renderTOC bool) (converter.Result, error) } // FileProvider provides the source file. type FileProvider interface { + // File returns the source file for this Page, + // or a zero File if this Page is not backed by a file. File() source.File } @@ -131,13 +134,17 @@ type GetPageProvider interface { // GitInfoProvider provides Git info. type GitInfoProvider interface { - GitInfo() *gitmap.GitInfo + // GitInfo returns the Git info for this object. + GitInfo() source.GitInfo + // CodeOwners returns the code owners for this object. CodeOwners() []string } // InSectionPositioner provides section navigation. type InSectionPositioner interface { + // NextInSection returns the next page in the same section. NextInSection() Page + // PrevInSection returns the previous page in the same section. PrevInSection() Page } @@ -149,6 +156,7 @@ type InternalDependencies interface { // OutputFormatsProvider provides the OutputFormats of a Page. type OutputFormatsProvider interface { + // OutputFormats returns the OutputFormats for this Page. OutputFormats() OutputFormats } @@ -229,6 +237,7 @@ type PageMetaProvider interface { SectionsPath() string // Sitemap returns the sitemap configuration for this page. + // This is for internal use only. Sitemap() config.Sitemap // Type is a discriminator used to select layouts etc. It is typically set @@ -242,7 +251,15 @@ type PageMetaProvider interface { // PageRenderProvider provides a way for a Page to render content. type PageRenderProvider interface { + // Render renders the given layout with this Page as context. Render(layout ...string) (template.HTML, error) + // RenderString renders the first value in args with tPaginatorhe content renderer defined + // for this Page. + // It takes an optional map as a second argument: + // + // display (“inline”): + // - inline or block. If inline (default), surrounding <p></p> on short snippets will be trimmed. + // markup (defaults to the Page’s markup) RenderString(args ...any) (template.HTML, error) } @@ -311,7 +328,9 @@ type PageWithoutContent interface { // Positioner provides next/prev navigation. type Positioner interface { + // Next points up to the next regular page (sorted by Hugo’s default sort). Next() Page + // Prev points down to the previous regular page (sorted by Hugo’s default sort). Prev() Page // Deprecated: Use Prev. Will be removed in Hugo 0.57 @@ -323,16 +342,19 @@ type Positioner interface { // RawContentProvider provides the raw, unprocessed content of the page. type RawContentProvider interface { + // RawContent returns the raw, unprocessed content of the page excluding any front matter. RawContent() string } // RefProvider provides the methods needed to create reflinks to pages. type RefProvider interface { + // Ref returns an absolute URl to a page. Ref(argsm map[string]any) (string, error) // RefFrom is for internal use only. RefFrom(argsm map[string]any, source any) (string, error) + // RelRef returns a relative URL to a page. RelRef(argsm map[string]any) (string, error) // RefFrom is for internal use only. @@ -356,12 +378,15 @@ type ShortcodeInfoProvider interface { // SitesProvider provide accessors to get sites. type SitesProvider interface { + // Site returns the current site. Site() Site + // Sites returns all sites. Sites() Sites } // TableOfContentsProvider provides the table of contents for a Page. type TableOfContentsProvider interface { + // TableOfContents returns the table of contents for the page rendered as HTML. TableOfContents() template.HTML } @@ -382,7 +407,7 @@ type TranslationsProvider interface { // TreeProvider provides section tree navigation. type TreeProvider interface { - // IsAncestor returns whether the current page is an ancestor of the given + // IsAncestor returns whether the current page is an ancestor of other. // Note that this method is not relevant for taxonomy lists and taxonomy terms pages. IsAncestor(other any) (bool, error) @@ -390,7 +415,7 @@ type TreeProvider interface { // Note that this will return nil for pages that is not regular, home or section pages. CurrentSection() Page - // IsDescendant returns whether the current page is a descendant of the given + // IsDescendant returns whether the current page is a descendant of other. // Note that this method is not relevant for taxonomy lists and taxonomy terms pages. IsDescendant(other any) (bool, error) @@ -398,7 +423,7 @@ type TreeProvider interface { // For the home page, this will return itself. FirstSection() Page - // InSection returns whether the given page is in the current section. + // InSection returns whether other is in the current section. // Note that this will always return false for pages that are // not either regular, home or section pages. InSection(other any) (bool, error) diff --git a/resources/page/page_marshaljson.autogen.go b/resources/page/page_marshaljson.autogen.go index 0f73d81ae..373257878 100644 --- a/resources/page/page_marshaljson.autogen.go +++ b/resources/page/page_marshaljson.autogen.go @@ -17,7 +17,6 @@ package page import ( "encoding/json" - "github.com/bep/gitmap" "github.com/gohugoio/hugo/common/maps" "github.com/gohugoio/hugo/config" "github.com/gohugoio/hugo/hugofs/files" @@ -82,6 +81,7 @@ func MarshalPageToJSON(p Page) ([]byte, error) { language := p.Language() file := p.File() gitInfo := p.GitInfo() + codeOwners := p.CodeOwners() outputFormats := p.OutputFormats() alternativeOutputFormats := p.AlternativeOutputFormats() menus := p.Menus() @@ -89,10 +89,11 @@ func MarshalPageToJSON(p Page) ([]byte, error) { isTranslated := p.IsTranslated() allTranslations := p.AllTranslations() translations := p.Translations() + store := p.Store() getIdentity := p.GetIdentity() s := struct { - Content any + Content interface{} Plain string PlainWords []string Summary template.HTML @@ -110,7 +111,7 @@ func MarshalPageToJSON(p Page) ([]byte, error) { Name string Title string Params maps.Params - Data any + Data interface{} Date time.Time Lastmod time.Time PublishDate time.Time @@ -139,7 +140,8 @@ func MarshalPageToJSON(p Page) ([]byte, error) { Weight int Language *langs.Language File source.File - GitInfo *gitmap.GitInfo + GitInfo source.GitInfo + CodeOwners []string OutputFormats OutputFormats AlternativeOutputFormats OutputFormats Menus navigation.PageMenus @@ -147,6 +149,7 @@ func MarshalPageToJSON(p Page) ([]byte, error) { IsTranslated bool AllTranslations Pages Translations Pages + Store *maps.Scratch GetIdentity identity.Identity }{ Content: content, @@ -197,6 +200,7 @@ func MarshalPageToJSON(p Page) ([]byte, error) { Language: language, File: file, GitInfo: gitInfo, + CodeOwners: codeOwners, OutputFormats: outputFormats, AlternativeOutputFormats: alternativeOutputFormats, Menus: menus, @@ -204,6 +208,7 @@ func MarshalPageToJSON(p Page) ([]byte, error) { IsTranslated: isTranslated, AllTranslations: allTranslations, Translations: translations, + Store: store, GetIdentity: getIdentity, } diff --git a/resources/page/page_nop.go b/resources/page/page_nop.go index 15f8c3950..c4af3f554 100644 --- a/resources/page/page_nop.go +++ b/resources/page/page_nop.go @@ -28,7 +28,6 @@ import ( "github.com/gohugoio/hugo/hugofs" - "github.com/bep/gitmap" "github.com/gohugoio/hugo/navigation" "github.com/gohugoio/hugo/common/hugo" @@ -200,8 +199,8 @@ func (p *nopPage) GetTerms(taxonomy string) Pages { return nil } -func (p *nopPage) GitInfo() *gitmap.GitInfo { - return nil +func (p *nopPage) GitInfo() source.GitInfo { + return source.GitInfo{} } func (p *nopPage) CodeOwners() []string { diff --git a/resources/page/pagination.go b/resources/page/pagination.go index 9f4bfcff5..46d9fda82 100644 --- a/resources/page/pagination.go +++ b/resources/page/pagination.go @@ -27,8 +27,10 @@ import ( // PaginatorProvider provides two ways to create a page paginator. type PaginatorProvider interface { + // Paginator creates a paginator with the default page set. Paginator(options ...any) (*Pager, error) - Paginate(seq any, options ...any) (*Pager, error) + // Paginate creates a paginator with the given page set in pages. + Paginate(pages any, options ...any) (*Pager, error) } // Pager represents one of the elements in a paginator. diff --git a/resources/page/site.go b/resources/page/site.go index f5806280c..8daff95ae 100644 --- a/resources/page/site.go +++ b/resources/page/site.go @@ -26,8 +26,7 @@ import ( "github.com/gohugoio/hugo/navigation" ) -// Site represents a site in the build. This is currently a very narrow interface, -// but the actual implementation will be richer, see hugolib.SiteInfo. +// Site represents a site. There can be multople sites in a multilingual setup. type Site interface { // Returns the Language configured for this Site. Language() *langs.Language @@ -63,7 +62,7 @@ type Site interface { BaseURL() template.URL // Retuns a taxonomy map. - Taxonomies() any + Taxonomies() TaxonomyList // Returns the last modification date of the content. LastChange() time.Time @@ -142,7 +141,7 @@ func (t testSite) Menus() navigation.Menus { return nil } -func (t testSite) Taxonomies() any { +func (t testSite) Taxonomies() TaxonomyList { return nil } diff --git a/resources/page/taxonomy.go b/resources/page/taxonomy.go new file mode 100644 index 000000000..f50152f90 --- /dev/null +++ b/resources/page/taxonomy.go @@ -0,0 +1,168 @@ +// Copyright 2023 The Hugo Authors. All rights reserved. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package page + +import ( + "fmt" + "sort" + + "github.com/gohugoio/hugo/compare" + "github.com/gohugoio/hugo/langs" +) + +// The TaxonomyList is a list of all taxonomies and their values +// e.g. List['tags'] => TagTaxonomy (from above) +type TaxonomyList map[string]Taxonomy + +func (tl TaxonomyList) String() string { + return fmt.Sprintf("TaxonomyList(%d)", len(tl)) +} + +// A Taxonomy is a map of keywords to a list of pages. +// For example +// +// TagTaxonomy['technology'] = WeightedPages +// TagTaxonomy['go'] = WeightedPages +type Taxonomy map[string]WeightedPages + +// OrderedTaxonomy is another representation of an Taxonomy using an array rather than a map. +// Important because you can't order a map. +type OrderedTaxonomy []OrderedTaxonomyEntry + +// getOneOPage returns one page in the taxonomy, +// nil if there is none. +func (t OrderedTaxonomy) getOneOPage() Page { + if len(t) == 0 { + return nil + } + return t[0].Pages()[0] +} + +// OrderedTaxonomyEntry is similar to an element of a Taxonomy, but with the key embedded (as name) +// e.g: {Name: Technology, WeightedPages: TaxonomyPages} +type OrderedTaxonomyEntry struct { + Name string + WeightedPages +} + +// Get the weighted pages for the given key. +func (i Taxonomy) Get(key string) WeightedPages { + return i[key] +} + +// Count the weighted pages for the given key. +func (i Taxonomy) Count(key string) int { return len(i[key]) } + +// TaxonomyArray returns an ordered taxonomy with a non defined order. +func (i Taxonomy) TaxonomyArray() OrderedTaxonomy { + ies := make([]OrderedTaxonomyEntry, len(i)) + count := 0 + for k, v := range i { + ies[count] = OrderedTaxonomyEntry{Name: k, WeightedPages: v} + count++ + } + return ies +} + +// Alphabetical returns an ordered taxonomy sorted by key name. +func (i Taxonomy) Alphabetical() OrderedTaxonomy { + ia := i.TaxonomyArray() + p := ia.getOneOPage() + if p == nil { + return ia + } + currentSite := p.Site().Current() + coll := langs.GetCollator(currentSite.Language()) + coll.Lock() + defer coll.Unlock() + name := func(i1, i2 *OrderedTaxonomyEntry) bool { + return coll.CompareStrings(i1.Name, i2.Name) < 0 + } + oiBy(name).Sort(ia) + return ia +} + +// ByCount returns an ordered taxonomy sorted by # of pages per key. +// If taxonomies have the same # of pages, sort them alphabetical +func (i Taxonomy) ByCount() OrderedTaxonomy { + count := func(i1, i2 *OrderedTaxonomyEntry) bool { + li1 := len(i1.WeightedPages) + li2 := len(i2.WeightedPages) + + if li1 == li2 { + return compare.LessStrings(i1.Name, i2.Name) + } + return li1 > li2 + } + + ia := i.TaxonomyArray() + oiBy(count).Sort(ia) + return ia +} + +// Pages returns the Pages for this taxonomy. +func (ie OrderedTaxonomyEntry) Pages() Pages { + return ie.WeightedPages.Pages() +} + +// Count returns the count the pages in this taxonomy. +func (ie OrderedTaxonomyEntry) Count() int { + return len(ie.WeightedPages) +} + +// Term returns the name given to this taxonomy. +func (ie OrderedTaxonomyEntry) Term() string { + return ie.Name +} + +// Reverse reverses the order of the entries in this taxonomy. +func (t OrderedTaxonomy) Reverse() OrderedTaxonomy { + for i, j := 0, len(t)-1; i < j; i, j = i+1, j-1 { + t[i], t[j] = t[j], t[i] + } + + return t +} + +// A type to implement the sort interface for TaxonomyEntries. +type orderedTaxonomySorter struct { + taxonomy OrderedTaxonomy + by oiBy +} + +// Closure used in the Sort.Less method. +type oiBy func(i1, i2 *OrderedTaxonomyEntry) bool + +func (by oiBy) Sort(taxonomy OrderedTaxonomy) { + ps := &orderedTaxonomySorter{ + taxonomy: taxonomy, + by: by, // The Sort method's receiver is the function (closure) that defines the sort order. + } + sort.Stable(ps) +} + +// Len is part of sort.Interface. +func (s *orderedTaxonomySorter) Len() int { + return len(s.taxonomy) +} + +// Swap is part of sort.Interface. +func (s *orderedTaxonomySorter) Swap(i, j int) { + s.taxonomy[i], s.taxonomy[j] = s.taxonomy[j], s.taxonomy[i] +} + +// Less is part of sort.Interface. It is implemented by calling the "by" closure in the sorter. +func (s *orderedTaxonomySorter) Less(i, j int) bool { + return s.by(&s.taxonomy[i], &s.taxonomy[j]) +} diff --git a/resources/page/testhelpers_test.go b/resources/page/testhelpers_test.go index 22346c389..e8275ba40 100644 --- a/resources/page/testhelpers_test.go +++ b/resources/page/testhelpers_test.go @@ -26,7 +26,6 @@ import ( "github.com/gohugoio/hugo/modules" - "github.com/bep/gitmap" "github.com/gohugoio/hugo/helpers" "github.com/gohugoio/hugo/resources/resource" @@ -250,8 +249,8 @@ func (p *testPage) GetRelatedDocsHandler() *RelatedDocsHandler { return relatedDocsHandler } -func (p *testPage) GitInfo() *gitmap.GitInfo { - return nil +func (p *testPage) GitInfo() source.GitInfo { + return source.GitInfo{} } func (p *testPage) CodeOwners() []string { diff --git a/resources/resource/resources.go b/resources/resource/resources.go index a888d6fb4..a877c8906 100644 --- a/resources/resource/resources.go +++ b/resources/resource/resources.go @@ -1,4 +1,4 @@ -// Copyright 2019 The Hugo Authors. All rights reserved. +// Copyright 2023 The Hugo Authors. All rights reserved. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. @@ -11,6 +11,7 @@ // See the License for the specific language governing permissions and // limitations under the License. +// Package resource contains Resource related types. package resource import ( diff --git a/resources/resource/resourcetypes.go b/resources/resource/resourcetypes.go index 4ba95c170..4ef5fc5a0 100644 --- a/resources/resource/resourcetypes.go +++ b/resources/resource/resourcetypes.go @@ -64,6 +64,9 @@ type ResourceError interface { // ErrProvider provides an Err. type ErrProvider interface { + + // Err returns an error if this resource is in an error state. + // This will currently only be set for resources obtained from resources.GetRemote. Err() ResourceError } |