quantum-version

About

This module provides a file transform that enables the generation of incrementally versioned content. The version transform works well with the quantum-api entity transforms for generating versioned api documentation.

This module provides a few entity types for labelling up versioned content. With these labels, it is possible to include content only for certain version ranges. Here are some examples of what is possible:

# This function was added in version 1.0.0. By giving it the @added 1.0.0
# tag, it will only be included in pages with version 0.1.0 and later
@function myFunction
  @added 0.1.0
  @description
    # Versioned content provides alternative versions of content for
    # different versions. Between versions, the content does not change -
    # for example, for version 0.1.1, the description will still be
    # "Description 1"
    @versioned
      @version 0.1.0: Description 1
      @version 0.2.0: Description 2

@arg x [Number]
  @description
    Some Description

# Only included in versions 0.2.0 and later, and gets removed after 0.4.0
@arg y [Number]
  @added 0.2.0
  @deprecated 0.3.0
  @removed 0.4.0
  @description
    @versioned
      @version 0.2.0: Description 1
      @version 0.4.0: Description 2

There are a few entity types that can be used to label versioned content:

Typically the @added, @deprecated and @removed tags are used in @api sections, and have the following meanings:

The @added tag indicates that some content should only be included from the version specified onwards.
The @deprecated tag indicates that something is going to be removed (from an api), and should no longer be used.
The @removed tag indicates that the something was removed. The entity with this tag will remain on the page for the version given, but will not be included for versions greater than the version specified.

API

Below are all the properties of the object returned from require('quantum-version'). For information about different versions, see the Changelog

File Transform

fileTransformoptionsObjectFileTransformadded

Creates pipeline transformation functions for quantum-version. This function takes the config for configuring quantum version, and returns a function for transforming pages (a FileTransform ).

Arguments

options

Properties

filenameModifierFileInfo

This is a function which modifies the filename of the file to include the version. By default the version is added to the end of the filename. For example target/api/index.html becomes target/api/0.1.0/index.html

Default:

function filenameModifier (fileInfo, version) {
  if (fileInfo.dest.endsWith('index.um')) {
    return fileInfo.clone({
      dest: fileInfo.dest.replace('index.um', version) + '/' + 'index.um'
})
} else {
  return fileInfo.clone({
    dest: fileInfo.dest.replace('.um', '') + '/' + version + '.um'
})
}
}

Returns

FileInfo

Returns a new FileInfo instance, or a clone of the one passed in.

outputLatestBoolean

Whether or not to output the latest page without the version included in the url. When this option is turned on, it would output something like

target/api/1.0.0/index.html
target/api/1.1.0/index.html
target/api/1.2.0/index.html
target/api/index.html          <- The same as target/api/1.2.0/index.html

When this option is set to false, only the following pages are output:

target/api/1.0.0/index.html
target/api/1.1.0/index.html
target/api/1.2.0/index.html

Default: true

versionsArray[String]

An array of versions the versioned content uses. This can be left undefined if the a @versionedPage entity is included on the page which contains the versions.

If both a @versionedPage entity is found for a page, and this option is set, the option takes precedence.

Returns

FileTransform

Returns a new FileTransform function which can expand a File instance into multiple File instances - one for each version.

Entities

addedadded

Can be added to any content that should only be included in the page starting from a certain version.

For example, this function will only be included in pages with version 2.1.0 or later:

Example Markup

Quantum

@versionedPage
  @version 2.0.0

@api
  @function myFunction
    @added 2.0.0
      @description
        The content of the description block will be shown in the api
        section.
@arg a [Number]
@arg b [number]
@return Number

Example Result

Functions

myFunctionadded

Added

The content of the description block will be shown in the api section.

aNumber

bnumber

The automatic changelog generation in quantum-api also uses these tags to build up a summary of what has changed from one version to the next.

deprecatedadded

This tag has no real affect on the content that is output, but when other modules are used, such as quantum-api, this tag can have an affect on the visible output - for quantum-api a notice is displayed in the api section.

Normally a deprecated tag will sit before a @removed tag.

Example Markup

Quantum

@versionedPage
  @version 2.0.0

@api
  @function myFunction
    @deprecated 2.0.0
      @description
        The content of the description block will be shown in the api
        section.
@arg a [Number]
@arg b [number]
@return Number

Example Result

Functions

myFunctiondeprecated

Deprecated

The content of the description block will be shown in the api section.

aNumber

bnumber

The automatic changelog generation in quantum-api also uses these tags to build up a summary of what has changed from one version to the next.

Entities

description

The description that the

removedadded

Can be added to any content that should stop being included in the page after a certain version. The content will remain in the page for the version specified, but any versions later than the one given will not include the content.

For example, this function will only be included in pages from versions 2.1.0 up to 3.0.0:

Example Markup

Quantum

@versionedPage
  @version 2.0.0

@api
  @function myFunction
    @removed 2.0.0
      @description
        The content of the description block will be shown in the api
        section.
@arg a [Number]
@arg b [number]
@return Number

Example Result

Functions

myFunctionremoved

Removed

The content of the description block will be shown in the api section.

aNumber

bnumber

The automatic changelog generation in quantum-api also uses these tags to build up a summary of what has changed from one version to the next.

updatedadded

This tag has no real affect on the content that is output, but when other modules are used, such as quantum-api, this tag can have an affect on the visible output. A notice will be displayed for just the version specified. The content for the notice will be taken from the @description tag.

Example Markup

Quantum

@versionedPage
  @version 2.0.0

@api
  @function myFunction
    @updated 2.0.0
      @description
        The content of the description block will be shown in the api
        section.
@arg a [Number]
@arg b [number]
@return Number

Example Result

Functions

myFunctionupdated

Updated

The content of the description block will be shown in the api section.

aNumber

bnumber

The automatic changelog generation in quantum-api also uses these tags to build up a summary of what has changed from one version to the next.

versionListadded

An entity that will be populated with the full list of versions and the current version when the file is processed by the version page transform.

Given this input:

index.um

@versionedPage
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0

@versionList

The output will be (3 separate files)

1.0.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 1.0.0

1.1.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 1.1.0

2.0.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 2.0.0

versionedadded

Versioned content provides alternative versions of content for different versions. It does a full replacement for each version. Content remains the same between versions.

Given this input:

index.um

@versionedPage
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0

@versioned
  @version 1.0.0: Description 1
  @version 2.0.0: Description 2

The output will be (3 separate files)

1.0.0/index.um

Description 1

1.1.0/index.um

Description 1

2.0.0/index.um

Description 2

versionedPageadded

This marks a page as "versioned", which means that it will be processed by the version fileTransform. Any pages without this entity will pass through the version file transform untouched.

The list of versions for this page can be included in this entity. An alternative way of doing this is to set the list of entities in the options passed into version.fileTransform() in the quantum.config.json.

Example: when the versions are set in quantum.config.json

@versionedPage

Example: specifying the versions in the page itself

@versionedPage
  @version 1.0.0
  @version 1.1.0
  @version 1.2.0
  @version 1.2.1
  @version 1.3.0
  @version 2.0.0

Example: Using inlining

index.um

@versionedPage
  @inline ./versions.um

versions.um

@version 1.0.0
@version 1.1.0
@version 1.2.0
@version 1.2.1
@version 1.3.0
@version 2.0.0

Entities

version

Describes one of the versions for this page

Utilities

processTagsentityEntityversionStringversionsArray[String]fileFileadded

Processes all the tags in the content passed in. This involves only keeping content that satisfy the @added and @removed tags for the version specified.

The @updated and @deprecated tags are removed if they do not apply to the version passed in.

Arguments

entityEntity

The entity to process the tags for

versionString

The version to process the tags for

versionsArray[String]

The full list of versions available for the content being passed in

fileFile

The file the content originated from (this is so that errors can be reported to the file)

processVersionListsentityEntitycurrentVersionStringversionsArray[String]added

Looks for all the @versionList entities in the entity passed in (recursively), and populates them with the full list of versions for the page, as well as the current version.

This function handles the following functionality:

Given this input:

index.um

@versionedPage
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0

@versionList

The output will be (3 separate files)

1.0.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 1.0.0

1.1.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 1.1.0

2.0.0/index.um

@versionList
  @version 1.0.0
  @version 1.1.0
  @version 2.0.0
  @current 2.0.0

Arguments

entityEntity

The entity to look for @versionList entities to populate

currentVersionString

The version to populate as the @current version

versionsArray[String]

The full list of versions to populate in the @versionList entities that are found

processVersionedentityEntityversionStringversionsArray[String]added

Processes the @versioned sections in the entity passed in. This removes all @versioned sections from the entity (recursively) and replaces then with the correct content for the version given.

Example

const version = require('quantum-version')

const entity = {
  params: [],
  content: [
    {
      type: 'versioned',
      params: [],
      content: [
        {
          type: 'version',
          params: ['0.1.0'],
          content: [
            "Content1"
]
},
{
  type: 'version',
  params: ['0.3.0'],
  content: [
    "Content2"
]
}
]
}
]
}

const versions = ['0.1.0', '0.2.0', '0.3.0']

version.processVersioned(entity, '0.1.0', versions)
console.log(entity)
// { params: [], content: ['Content1'] }

version.processVersioned(entity, '0.2.0', versions)
console.log(entity)
// { params: [], content: ['Content1'] }

version.processVersioned(entity, '0.3.0', versions)
console.log(entity)
// { params: [], content: ['Content2'] }

Arguments

entityEntity

The entity to process

versionString

The version to target when processing the @versioned blocks

versionsArray[String]

The full list of versions possible