Skip to content

WRP-1050: Migrated docs-utils to ES Modules #28

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .eslintrc.js → .eslintrc.cjs
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ module.exports = {
'mocha': true
},
parserOptions: {
'ecmaVersion': 'latest'
'ecmaVersion': 'latest',
'sourceType': 'module'
},
root: true,
extends: ['eslint:recommended'],
Expand Down
61 changes: 24 additions & 37 deletions index.js
Original file line number Diff line number Diff line change
@@ -1,30 +1,28 @@
#!/usr/bin/env node

'use strict';

/* eslint-env node */
// For `--standalone` the `--path` needs to include the library name or point to `packages`, no
// trailing `/`. Defaults to the current working directory.

// TODO: Allow for configuring output and input dirs better
// TODO: Consider returning useful values from functions instead of just outputting/saving/etc.

const shelljs = require('shelljs'),
fs = require('fs'),
os = require('os'),
pathModule = require('path'),
ProgressBar = require('progress'),
elasticlunr = require('elasticlunr'),
jsonata = require('jsonata'),
readdirp = require('readdirp'),
mkdirp = require('mkdirp'),
toc = require('markdown-toc'),
jsonfile = require('jsonfile'),
chalk = require('chalk'),
matter = require('gray-matter'),
parseArgs = require('minimist');
const documentation = import('documentation');
import chalk from 'chalk';
import elasticlunr from 'elasticlunr';
import fs from 'fs';
import matter from 'gray-matter';
import jsonata from 'jsonata';
import jsonfile from 'jsonfile';
import toc from 'markdown-toc';
import parseArgs from 'minimist';
import {mkdirpSync} from 'mkdirp';
import os from 'os';
import pathModule from 'path';
import ProgressBar from 'progress';
import readdirp from 'readdirp';
import shelljs from 'shelljs';

const documentation = import('documentation');
let documentationResponse;
const generateDocumentationResponse = async () => {
documentationResponse = await documentation.then(result => result);
Expand All @@ -50,7 +48,7 @@ const allowedErrorTags = ['@curried', '@hoc', '@hocconfig', '@omit', '@required'
* @param {string} [pattern=*.js] - An optional regex string to be used for filtering files
* @returns {string[]} - A list of paths of matching files
*/
const getValidFiles = (modules, pattern = '*.js') => {
export const getValidFiles = (modules, pattern = '*.js') => {
const files = [];
let cmd, moduleFiles;

Expand Down Expand Up @@ -92,7 +90,7 @@ const getValidFiles = (modules, pattern = '*.js') => {
* @param {boolean} noSave - If `true`, no files are written to disk
* @returns {Promise[]} - An array of promises that represent the scanning process
*/
const getDocumentation = (paths, strict, noSave) => {
export const getDocumentation = (paths, strict, noSave) => {
const docOutputPath = pathModule.join('src', 'pages', 'docs', 'modules');
// TODO: Add @module to all files and scan files and combine json
const validPaths = paths.reduce((prev, path) => {
Expand Down Expand Up @@ -273,7 +271,7 @@ async function validate (docs, componentDirectory, strict) {
* @param {boolean} ignoreExternal - If `true`, any modules not scanned will be excluded from
* validation (i.e. standalone libraries will not warn for referencing core libraries)
*/
function postValidate (strict, ignoreExternal) {
export function postValidate (strict, ignoreExternal) {
const moduleRegex = /^((\w+\/\w+)(\.\w+)?)/,
exceptions = ['spotlight/Spotlight'];

Expand Down Expand Up @@ -361,7 +359,7 @@ function prependTableOfContents (contents) {
* @param {string} [path] - Parent directory of `/docs/config.json`
* @returns {object} Configuration object
*/
function getDocsConfig (path = process.cwd()) {
export function getDocsConfig (path = process.cwd()) {
const configFilename = `${path}/docs/config.json`,
// don't parse CLI or eslint-config-enact for source
parseSource = (path.indexOf('/cli') + path.indexOf('eslint')) < 0,
Expand Down Expand Up @@ -394,7 +392,7 @@ function getDocsConfig (path = process.cwd()) {
* @param {string} config.source - Path to search for docs directory (parent of docs dir)
* @param {string} config.outputTo - Path to copy static docs
*/
function copyStaticDocs ({source, outputTo: outputBase, icon}) {
export function copyStaticDocs ({source, outputTo: outputBase, icon}) {
let files = [];

if (os.platform() === 'win32') {
Expand Down Expand Up @@ -489,7 +487,7 @@ function copyStaticDocs ({source, outputTo: outputBase, icon}) {
* @param {boolean} [strict] - If `true`, set process exit code on warnings
* @returns {object} - keys = library names values = object {desc: description, version: version, etc.}
*/
function extractLibraryDescription ({path, hasPackageDir, description, ...rest}, strict) {
export function extractLibraryDescription ({path, hasPackageDir, description, ...rest}, strict) {
const output = {};
let libraryPaths;

Expand Down Expand Up @@ -576,7 +574,7 @@ function extractLibraryDescription ({path, hasPackageDir, description, ...rest},
*
* @param {string} outputFilename - Filename for the generated index file
*/
function generateIndex (docIndexFile) {
export function generateIndex (docIndexFile) {
// Note: The $map($string) is needed because spotlight has a literal 'false' in a return type!
const expression = `{
"title": name,
Expand Down Expand Up @@ -652,10 +650,10 @@ function generateIndex (docIndexFile) {
}

function makeDataDir () {
mkdirp.mkdirpSync(dataDir);
mkdirpSync(dataDir);
}

function saveLibraryDescriptions (descriptions) {
export function saveLibraryDescriptions (descriptions) {
makeDataDir();
// generate a json file that contains the description to the corresponding libraries
jsonfile.writeFileSync(libraryDescriptionFile, descriptions);
Expand All @@ -680,14 +678,3 @@ function init () {
}

init();

module.exports = {
getValidFiles,
getDocumentation,
postValidate,
copyStaticDocs,
generateIndex,
getDocsConfig,
extractLibraryDescription,
saveLibraryDescriptions
};
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
{
"name": "@enact/docs-utils",
"description": "Utilities for parsing and validating JSDoc in Enact projects",
"type": "module",
"version": "0.4.2",
"engines": {
"node": ">=14"
},
"main": "index.js",
"exports": "./index.js",
"bin": {
"validate-docs": "index.js"
},
Expand Down