Refactor to accept version option

Author: Planeshifter

lib/node_modules/@stdlib/_tools/docs/www/readme-database/README.md

@@ -52,6 +52,7 @@ The function accepts the following `options`:
 -   **dir**: root directory from which to search for package READMEs. May be either an absolute path or a path relative to the current working directory. Default: current working directory.
 -   **pattern**: glob pattern used to find packages. Default: `'**/package.json'` (note: pattern **must** end with `package.json`).
 -   **ignore**: list of glob patterns used to exclude matches.
+-   **version**: semantic versioning number or branch name.
 
 To search from an alternative directory, set the `dir` option.
 
@@ -110,6 +111,26 @@ function done( error, db ) {
 }
 ```
 
+To have internal URLs of the READMEs link to the correct version of the documentation, set the `version` option. 
+
+<!-- run-disable -->
+
+
+```javascript
+var opts = {
+    'version': '0.0.87'
+};
+
+create( opts, done );
+
+function done( error, db ) {
+    if ( error ) {
+        throw error;
+    }
+    console.log( JSON.stringify( db ) );
+}
+```
+
 </section>
 
 <!-- /.usage -->
@@ -182,6 +203,7 @@ Options:
   -V,    --version             Print the package version.
          --pattern pattern     Inclusion glob pattern.
          --ignore pattern      Exclusion glob pattern.
+         --semver version      Semantic versioning number or branch name.
 ```
 
 </section>

lib/node_modules/@stdlib/_tools/docs/www/readme-database/bin/cli

@@ -72,6 +72,9 @@ function main() {
 			opts.ignore = flags.ignore;
 		}
 	}
+	if ( flags.semver ) {
+		opts.version = flags.semver;
+	}
 	if ( args[ 0 ] ) {
 		opts.dir = args[ 0 ];
 	}

lib/node_modules/@stdlib/_tools/docs/www/readme-database/docs/usage.txt

@@ -7,4 +7,5 @@ Options:
   -V,    --version             Print the package version.
          --pattern pattern     Inclusion glob pattern.
          --ignore pattern      Exclusion glob pattern.
+         --semver version      Semantic versioning number or branch name.
 

lib/node_modules/@stdlib/_tools/docs/www/readme-database/etc/cli_opts.json

@@ -1,7 +1,8 @@
 {
 	"string": [
 		"pattern",
-		"ignore"
+		"ignore",
+		"semver"
 	],
 	"boolean": [
 		"help",

lib/node_modules/@stdlib/_tools/docs/www/readme-database/lib/defaults.json

@@ -1,4 +1,5 @@
 {
 	"pattern": "**/package.json",
-	"ignore": []
+	"ignore": [],
+	"version": "develop"
 }

lib/node_modules/@stdlib/_tools/docs/www/readme-database/lib/main.js

@@ -46,6 +46,7 @@ var debug = logger( 'readme-database:async' );
 * @param {string} [options.dir] - root directory from which to search for package READMEs
 * @param {string} [options.pattern='**\/package.json'] - glob pattern
 * @param {StringArray} [options.ignore] - glob pattern(s) to exclude matches
+* @param {string} [options.version='develop'] - semantic versioning number or branch name
 * @param {Function} clbk - callback
 * @throws {TypeError} options argument must be an object
 * @throws {TypeError} must provide valid options
@@ -130,7 +131,7 @@ function create( options, clbk ) {
 		debug( 'Finished reading files.' );
 
 		debug( 'Rendering file contents...' );
-		render( files, done );
+		render( files, opts.version, done );
 	}
 
 	/**

lib/node_modules/@stdlib/_tools/docs/www/readme-database/lib/render.js

@@ -43,10 +43,11 @@ var RE_HEADER = headerRegExp( 'Apache-2.0', 'markdown' );
 *
 * @private
 * @param {ObjectArray} files - Markdown files
+* @param {string} version - semantic versioning number or branch name
 * @param {Callback} clbk - callback to invoke upon completion
 * @returns {void}
 */
-function render( files, clbk ) {
+function render( files, version, clbk ) {
 	var total;
 	var i;
 
@@ -67,7 +68,7 @@ function render( files, clbk ) {
 
 		debug( 'Rendering file %d of %d: %s', i+1, total, files[ i ].file );
 		str = removeHeader( files[ i ].data, RE_HEADER );
-		toHTML( str, onRender );
+		toHTML( str, version, onRender );
 
 		/**
 		* Callback invoked after rendering a file.

lib/node_modules/@stdlib/_tools/docs/www/readme-database/lib/validate.js

@@ -42,6 +42,7 @@ var RE = /package\.json$/;
 * @param {string} [options.dir] - root directory from which to search for package READMEs
 * @param {string} [options.pattern] - glob pattern
 * @param {StringArray} [options.ignore] - glob pattern(s) to exclude matches
+* @param {string} [options.version] - semantic versioning number or branch name
 * @returns {(Error|null)} error object or null
 *
 * @example
@@ -81,6 +82,12 @@ function validate( opts, options ) {
 			return new TypeError( 'invalid option. `ignore` option must be a string array. Option: `' + opts.ignore + '`.' );
 		}
 	}
+	if ( hasOwnProp( options, 'version' ) ) {
+		opts.version = options.version;
+		if ( !isString( opts.version ) ) {
+			return new TypeError( 'invalid option. `version` option must be a primitive string. Option: `' + opts.dir + '`.' );
+		}
+	}
 	return null;
 }
 

lib/node_modules/@stdlib/_tools/docs/www/readme-fragment-file-tree/README.md

@@ -52,6 +52,7 @@ The function accepts the following `options`:
 -   **dir**: root directory from which to search for package READMEs. May be either an absolute path or a path relative to the current working directory. Default: current working directory.
 -   **pattern**: glob pattern used to find packages. Default: `'**/package.json'` (note: pattern **must** end with `package.json`).
 -   **ignore**: list of glob patterns used to exclude matches.
+-   **version**:  semantic versioning number or branch name.
 
 To search from an alternative directory, set the `dir` option.
 
@@ -110,6 +111,26 @@ function done( error ) {
 }
 ```
 
+To have internal URLs of the READMEs link to the correct version of the documentation, set the `version` option. 
+
+<!-- run-disable -->
+
+
+```javascript
+var opts = {
+    'version': '0.0.87'
+};
+
+build( './build', opts, done );
+
+function done( error ) {
+    if ( error ) {
+        throw error;
+    }
+    console.log( 'Finished' );
+}
+```
+
 </section>
 
 <!-- /.usage -->

lib/node_modules/@stdlib/_tools/docs/www/readme-fragment-file-tree/bin/cli

@@ -73,6 +73,9 @@ function main() {
 			opts.ignore = flags.ignore;
 		}
 	}
+	if ( flags.version ) {
+		opts.version = flags.version;
+	}
 	if ( !flags.out ) {
 		err = new Error( 'insufficient arguments. Must provide an output directory.' );
 		return cli.error( err, 1 );

lib/node_modules/@stdlib/_tools/docs/www/readme-fragment-file-tree/docs/usage.txt

@@ -7,5 +7,6 @@ Options:
   -V,    --version             Print the package version.
          --pattern pattern     Inclusion glob pattern.
          --ignore pattern      Exclusion glob pattern.
+         --semver version      Semantic versioning number or branch name.
   -o,    --out directory       Output directory.
 

lib/node_modules/@stdlib/_tools/docs/www/readme-fragment-file-tree/etc/cli_opts.json

@@ -2,7 +2,8 @@
 	"string": [
 		"pattern",
 		"ignore",
-		"out"
+		"out",
+		"semver"
 	],
 	"boolean": [
 		"help",

lib/node_modules/@stdlib/_tools/docs/www/readme-fragment-file-tree/lib/defaults.json

@@ -1,4 +1,5 @@
 {
 	"pattern": "**/package.json",
-	"ignore": []
+	"ignore": [],
+	"version": "develop"
 }

lib/node_modules/@stdlib/_tools/docs/www/readme-fragment-file-tree/lib/main.js

@@ -47,6 +47,7 @@ var debug = logger( 'readme-fragment-file-tree:async' );
 * @param {string} [options.dir] - root directory from which to search for package READMEs
 * @param {string} [options.pattern='**\/package.json'] - glob pattern
 * @param {StringArray} [options.ignore] - glob pattern(s) to exclude matches
+* @param {string} [options.version='develop'] - semantic versioning number or branch name
 * @param {Function} clbk - callback
 * @throws {TypeError} first argument must be a string
 * @throws {TypeError} options argument must be an object

lib/node_modules/@stdlib/_tools/docs/www/readme-fragment-file-tree/lib/validate.js

@@ -42,6 +42,7 @@ var RE = /package\.json$/;
 * @param {string} [options.dir] - root directory from which to search for package READMEs
 * @param {string} [options.pattern] - glob pattern
 * @param {StringArray} [options.ignore] - glob pattern(s) to exclude matches
+* @param {string} [options.version] - semantic versioning number or branch name
 * @returns {(Error|null)} error object or null
 *
 * @example
@@ -81,6 +82,12 @@ function validate( opts, options ) {
 			return new TypeError( 'invalid option. `ignore` option must be a string array. Option: `' + opts.ignore + '`.' );
 		}
 	}
+	if ( hasOwnProp( options, 'version' ) ) {
+		opts.version = options.version;
+		if ( !isString( opts.version ) ) {
+			return new TypeError( 'invalid option. `version` option must be a primitive string. Option: `' + opts.dir + '`.' );
+		}
+	}
 	return null;
 }
 

lib/node_modules/@stdlib/_tools/markdown/to-html/README.md

@@ -40,7 +40,7 @@ limitations under the License.
 var toHTML = require( '@stdlib/_tools/markdown/to-html' );
 ```
 
-#### toHTML( markdown, done )
+#### toHTML( markdown\[, version], done )
 
 Converts a Markdown `string` or [`Buffer`][node-buffer] to HTML.
 
@@ -56,6 +56,20 @@ function done( error, html ) {
 }
 ```
 
+By default, the plugin resolves package identifiers to the `develop` documentation. To specify an alternative version, set the `version` option.
+
+```javascript
+toHtml( '[@stdlib/boop](https://github.com/stdlib-js/stdlib)', 'v0.0.87', done );
+
+function done( error, html ) {
+    if ( error ) {
+        throw error;
+    }
+    console.log( html );
+    // => '<a href="https://stdlib.io/v0.0.87/docs/api/@stdlib/boop">@stdlib/boop</a>'
+}
+```
+
 </section>
 
 <!-- /.usage -->
@@ -125,6 +139,7 @@ Options:
 
   -h,    --help                Print this message.
   -V,    --version             Print the package version.
+         --semver version      Semantic versioning number or branch name.
 ```
 
 </section>

lib/node_modules/@stdlib/_tools/markdown/to-html/bin/cli

@@ -65,7 +65,11 @@ function main() {
 	if ( !process.stdin.isTTY ) {
 		return stdin( onRead );
 	}
-	toHTML( replace( args[ 0 ], /\\n/g, '\n' ), done );
+	if ( flags.semver ) {
+		toHTML( replace( args[ 0 ], /\\n/g, '\n' ), flags.semver, done );
+	} else {
+		toHTML( replace( args[ 0 ], /\\n/g, '\n' ), done );
+	}
 
 	/**
 	* Callback invoked upon reading from `stdin`.
@@ -79,7 +83,11 @@ function main() {
 		if ( error ) {
 			return done( error );
 		}
-		toHTML( data.toString(), done );
+		if ( flags.semver ) {
+			toHTML( data.toString(), flags.semver, done );
+		} else {
+			toHTML( data.toString(), done );
+		}
 	}
 
 	/**

lib/node_modules/@stdlib/_tools/markdown/to-html/docs/usage.txt

@@ -5,4 +5,6 @@ Options:
 
   -h,    --help                Print this message.
   -V,    --version             Print the package version.
+         --semver version      Semantic versioning number or branch name.
+
 

lib/node_modules/@stdlib/_tools/markdown/to-html/etc/cli_opts.json

@@ -1,4 +1,7 @@
 {
+	"string": [
+		"semver"
+	],
 	"boolean": [
 		"help",
 		"version"

lib/node_modules/@stdlib/_tools/markdown/to-html/lib/convert.js

@@ -36,13 +36,6 @@ var postProcess = require( './post_process.js' );
 
 // VARIABLES //
 
-var mTransform = remark()
-	.use( headings )
-	.use( linkify )
-	.use( equations )
-	.use( toHTML )
-	.process;
-
 var hopts = {
 	'fragment': true
 };
@@ -59,6 +52,7 @@ var hTransform = rehype()
 * Converts Markdown to HTML.
 *
 * @param {(string|Buffer)} markdown - markdown to convert
+* @param {string} [version='develop'] - semantic versioning number or branch name
 * @param {Function} clbk - callback to invoke on completion
 * @throws {TypeError} first argument must be either a string or a Buffer
 * @throws {TypeError} last argument must be a function
@@ -75,16 +69,42 @@ var hTransform = rehype()
 *     console.log( html );
 * }
 */
-function convert( markdown, clbk ) {
+function convert( markdown ) {
+	var mTransform;
+	var version;
+	var clbk;
 	if (
 		!isString( markdown ) &&
 		!isBuffer( markdown )
 	) {
 		throw new TypeError( 'invalid argument. First argument must be either a string or a Buffer. Value: `'+markdown+'`.' );
 	}
-	if ( !isFunction( clbk ) ) {
-		throw new TypeError( 'invalid argument. Last argument must be a callback function. Value: `'+clbk+'`.' );
+	if ( arguments.length === 2 ) {
+		version = 'develop';
+		clbk = arguments[ 1 ];
+		if ( !isFunction( clbk ) ) {
+			throw new TypeError( 'invalid argument. Last argument must be a callback function. Value: `'+clbk+'`.' );
+		}
 	}
+	else {
+		version = arguments[ 1 ];
+		clbk = arguments[ 2 ];
+		if ( !isString( version ) ) {
+			throw new TypeError( 'invalid argument. Version argument must be a string primitive. Value: `'+version+'`.' );
+		}
+		if ( !isFunction( clbk ) ) {
+			throw new TypeError( 'invalid argument. Last argument must be a callback function. Value: `'+clbk+'`.' );
+		}
+	}
+	mTransform = remark()
+		.use( headings )
+		.use( linkify, {
+			'version': version
+		})
+		.use( equations )
+		.use( toHTML )
+		.process;
+
 	// Convert the Markdown to HTML:
 	mTransform( markdown.toString(), onMarkdownTransform );