shinstrap repo

Namespace: view

template/publish~ view

This is the jsdoc template handler. It deals with and acts as the namespace for all templates executed by shinstrap in pursuit of rendering documentation for the doclets generated by jsdoc.

members

<static> layout

The layout to use for all templates rendered via shinstrap.

<static> supplementalCSS

The supplemental css resource file. Yes, we only allow one. Discovered via jsdoc's standard resource discovery mechanism.

methods

static find()

See:
  • jsdoc/util/templateHelper.find

static htmlsafe()

See:
  • `sanitize-html`

static linkto()

See:
  • jsdoc/util/templateHelper.linkto

static marshalItemDisplay()

See:
Redirected: module:template/publish.utils.marshalItemDisplay

static utils.marshalItemDisplay(_item, _marshallingRules, _view)

This is the handler function for the itemMarshalling rule. This function will interpret the arrangment and the marshalling rules in the context of the indicated _item to derive the appropriate parameters, invoke the indicated function and return the result to the calling template.

Parameters:
Name Type Description
_item object

The display item or doclet being marshalled.
_marshallingRules object

The marshalling rules which dictate the handling of this item's marshalling.
_view object

The template view which is handing the rendering of this listing.
Returns:

"marshalled" html representation for _item as indicated in the _marshallingRules.

Type
string

static moment()

See:
  • `moment`

static partial(_file, _data)

This is an instance "patch" override of jsdoc's core Template class's partial() function. This patch implements the templateOverrideDir functionality. partial() in turn handles the caching and invocation of a template in jsdoc. {@see jsdoc/template.Template#partial}

Parameters:
Name Type Description
_file string

Name of the template file to render.
_data object

If the template is not scaffolded this is the doclet or doclet-shard (typically called data in this framework) which is to be rendered. A "scaffolded" template expects an object with, minimally the doclet/data in a field called contents and the rendering rules in a field called scaffolding.
ToDo:

  • Originally I thought this made more sense and was less invasive as an instance override, but now I'm coming around to the idea that it should probably be a direct patch on Template, given I really am the only client of that class in the framework.

static renderDoclet()

See:
Redirected: module:template/publish.utils.renderDoclet

static utils.renderDoclet(_arrangement, _defaults, _docOrData)

The default rendering pattern for a sectioned/named renderer (template).

Parameters:
Name Type Description
_arrangement object

The rules array for the doclet/fragment being rendered.
_defaults array

The default array of entries which are expected/valide for this doclet.
_docOrData object | array | string

The doclet or fragment being rendered.
ToDo:

  • Once I'm satisfied, this function should probably replace all the renderer snippets.

static resolveArrangement()

See:
Redirected: module:template/publish.utils.resolveArrangement

static utils.resolveArrangement(_aSelectors)

This function resolves two sets of information for doclets of the specified selectors...

  1. It will determine the order which tags are intended to be displayed in the listing.
  2. It will generate the tags descriptor object for all tags.
    This information is derived from the conf settings passed into the publish module.
remarks

I debate here whether I should capture in the closure the entirety of conf.customizeOutput or if I should instead pass it in on the stack (which might also allow for some recursive/contextual resolution in the future)...

Parameters:
Name Type Description
_aSelectors Array

An array of selectors indicating for which context to resolve the arrangement information. The last (most specific) specifier in the array may be replaced by "default" (although because of the behavior for unrecognized specifiers, this is just a convention)
Returns:

An object consisting of two fields--An order field as an array of listings to be displayed, and a tags field containing any custom listing specifications for that section. If the specified path is not found, the default arrangment will be returned ({ order: [ "*" ] , tags: {} }). If the specified path exists, but the specific specifier does not (e.g. container:article:body:module-with-modules) this function will return the default arrangement for that path, as specified in the all keyword, if present.

{ order: [ "description", "notes", "remarks", "*" ], tags: {} }

Type
object
Example 
var arrangement = resolveArrangement([ "container", "article", "body", "default" ]);
See:
  • jsdoc/util/templateHelper.resolveAuthorLinks

static scaffoldPartial()

See:
Redirected: module:template/publish.utils.handleScaffolding

static utils.handleScaffolding(_tmpl, _doclet, _arrangement, _listing, _title)

This is the primary helper function for the new custom listing mechanism. All listings are now routed through this method and, in conjunction with listing.scaffolded.general.tmpl, the capabilities of the custom listing declarations are enabled.

Parameters:
Name Type Description
_tmpl object

The template object for which this function is doing the scaffolding
_doclet object

Doclet object being described
_arrangement object

Describes how the listing should be displayed
_listing string

The portion of the doclet being documented
_title string

The doclet title as understood in the current template. Not the title of the listing being documented.
Returns:

The rendered HTML for the doclet or doclet fragment passed in.

Type
string

static scaffoldPartialBySpec()

See:
Redirected: module:template/publish.utils.scaffoldFromSpecifier

static utils.scaffoldFromSpecifier(_tmpl, _doclet, _tagSpecifier)

This is a simple wrapper on module:template/publish.utils.handleScaffolding which will retrieve the rules for a listing from a specifier (and then call handleScaffolding with those rules for the specified listing).

Parameters:
Name Type Description
_tmpl object

The template object for which this function will be doing the scaffolding.
_doclet object

The doclet or fragment being rendered.
_tagSpecifier string

A colon-delimeted specifier to the rules which dictate the rendering pattern for the doclet.
Returns:

HTML for the doclet or doclet fragment passed in.

Type
string
See:
  • jsdoc/util/templateHelper.tutoriallink