diff --git a/tools/jsdoc/Check.js b/tools/jsdoc/Check.js deleted file mode 100644 index 8005db743a..0000000000 --- a/tools/jsdoc/Check.js +++ /dev/null @@ -1,225 +0,0 @@ -var fs = require('fs'); -var path = require('path'); -var request = require('request'); -var axios = require('axios'); - -var badLinks = []; -// var baseLink = `http://localhost:8000/api-reference/`; -var baseLink = `https://docs.highfidelity.com`; -var linkList = fs.readFileSync(__dirname + '/Links-Untouched','utf8').split('\n'); -// console.log("link list", linkList); -// console.log("filtered List", JSON.stringify(filteredList)); -var linkHash = {}; - -var currentGroup; -linkList.forEach( link => { - link = link.trim() - // console.log("link", link) - if (link.slice(-1) === ':'){ - currentGroup = link.slice(0, link.length-1); - // console.log("current Group: ", currentGroup); - linkHash[currentGroup] = {}; - } else { - if (!linkHash[currentGroup][link]){ - linkHash[currentGroup][link] = link; - } - } -}); - -// console.log("linkHash:", JSON.stringify(linkHash)) -var badLinks = []; - - -var stream = fs.createWriteStream("badLinks", {flags: 'a'}); -var linkReg = /="([\s\S]*?)"/g -var keys = Object.keys(linkHash); - -keys.forEach( key => { - for (var linkKey in linkHash[key]){ - var link = linkHash[key][linkKey]; - // console.log("link", link); - var extractLink = link.split(`"`)[1]; - - if (!(extractLink.indexOf(':') > -1)){ - console.log(" adding link") - extractLink = baseLink + extractLink; - } else { - // console.log("found https") - } - console.log("extractLink", extractLink) - - // console.log("about to make a request for", extractLink) - axios.get(extractLink) - .then( response => { - console.log("response") - if (response.status === 404){ - console.log("found bad link") - // console.log(JSON.stringify({file: key, link: extractLink})) - // stream.write(JSON.stringify({file: key, link: extractLink})); - } - }) - .catch( error => { - console.log("error") - // console.log(error); - // if (error.response.status === 404){ - // console.log("found bad link") - // console.log(JSON.stringify({file: key, link: extractLink})) - // stream.write(JSON.stringify({file: key, link: extractLink})); - // } - }) - } - }) -stream.end(); - -function endsWith(path, exts) { - var result = false; - exts.forEach(function(ext) { - if (path.endsWith(ext)) { - result = true; - } - }); - return result; -} - -function WarningObject(file, type, issues){ - this.file = file; - this.type = type; - this.issues = issues; -} - -var warnings = []; - -function parse() { - var rootFolder = __dirname; - console.log("Scanning hifi source for jsdoc comments..."); - - // directories to scan for jsdoc comments - var dirList = [ - '../../interface/src', - '../../interface/src/assets', - '../../interface/src/audio', - '../../interface/src/avatar', - '../../interface/src/commerce', - '../../interface/src/devices', - '../../interface/src/java', - '../../interface/src/networking', - '../../interface/src/ui/', - '../../interface/src/scripting', - '../../interface/src/ui/overlays', - '../../interface/src/raypick', - '../../libraries/animation/src', - '../../libraries/audio-client/src', - '../../libraries/audio/src', - '../../libraries/avatars/src', - '../../libraries/avatars-renderer/src/avatars-renderer', - '../../libraries/controllers/src/controllers/', - '../../libraries/controllers/src/controllers/impl/', - '../../libraries/display-plugins/src/display-plugins/', - '../../libraries/entities/src', - '../../libraries/graphics-scripting/src/graphics-scripting/', - '../../libraries/input-plugins/src/input-plugins', - '../../libraries/model-networking/src/model-networking/', - '../../libraries/networking/src', - '../../libraries/octree/src', - '../../libraries/physics/src', - '../../libraries/pointers/src', - '../../libraries/script-engine/src', - '../../libraries/shared/src', - '../../libraries/shared/src/shared', - '../../libraries/trackers/src/trackers', - '../../libraries/ui/src/ui', - '../../plugins/oculus/src', - '../../plugins/openvr/src' - ]; - - // only files with this extension will be searched for jsdoc comments. - var exts = ['.h', '.cpp']; - - dirList.forEach(function (dir) { - var joinedDir = path.join(rootFolder, dir); - var files = fs.readdirSync(joinedDir); - files.forEach(function (file) { - var pathDir = path.join(joinedDir, file); - if (fs.lstatSync(pathDir).isFile() && endsWith(pathDir, exts)) { - // load entire file into a string - var data = fs.readFileSync(pathDir, "utf8"); - var fileName = path.basename(file); - // var badJSDocWarnings = checkForBadJSDoc(data, fileName); - // if (badJSDocWarnings.length > 0){ - // warnings.push(badJSDocWarnings); - // } - // var badWordsList = checkForBadwordlist(data, fileName); - // if (badWordsList){ - // warnings.push(badWordsList); - // } - // var dotDescriptionList = checkForDotDescription(data, fileName); - // if (dotDescriptionList.length > 0){ - // warnings.push(dotDescriptionList); - // } - - - } - }); - }); -} - -function checkForBadJSDoc(dataToSearch, file){ - var warningList = []; - var reg = /\/\*\*js.*/g; - var matches = dataToSearch.match(reg); - if (matches) { - // add to source, but strip off c-comment asterisks - var filtered = matches.filter( item => { - return item.trim() !== '/**jsdoc'; - }); - if (filtered.length > 0){ - warningList.push(new WarningObject(file, "badJSDOC", filtered)); - } - } - return warningList; -} - -function checkForDotDescription(dataToSearch, file){ - var warningList = []; - var reg = /@property {.+?\..+?}/g - var matches = dataToSearch.match(reg); - if (matches) { - warningList.push(new WarningObject(file, "dotDescription", matches)); - } - return warningList; -} - -var badWordList = ["@params", "@return", "@bool"]; - -function checkForBadwordlist(dataToSearch, file){ - var warningList = []; - var reg = /(\/\*\*jsdoc(.|[\r\n])*?\*\/)/g; - var matches = dataToSearch.match(reg); - if (matches) { - var filtered = matches.forEach( item => { - var split = item.split(" "); - var filterList = []; - item.split(" ").forEach( item => { - badWordList.forEach(searchTerm => { - if (item === searchTerm) { - filterList.push(searchTerm); - } - }) - }) - if (filterList.length > 0) { - warningList.push(filterList); - } - }); - } - let flatten = warningList.reduce( (prev, cur) => { - return [...prev, ...cur]; - },[]) - let unique = [...new Set(flatten)]; - if (warningList.length > 0) { - return new WarningObject(file, "badWordList", unique); - } - -} - -parse(); -fs.writeFileSync(path.join(__dirname, "warningLog"), warnings.map( item => JSON.stringify(item)).join("\n")); \ No newline at end of file diff --git a/tools/jsdoc/grav.bat b/tools/jsdoc/grav.bat deleted file mode 100644 index 8ac0e4162a..0000000000 --- a/tools/jsdoc/grav.bat +++ /dev/null @@ -1 +0,0 @@ -node gravPrep true "D:\ROLC_High-Fidelity\02_Organize\O_Projects\Docs\hifi-docs-grav\user\themes\learn2" "D:\ROLC_High-Fidelity\02_Organize\O_Projects\Docs\hifi-docs-grav-content" \ No newline at end of file diff --git a/tools/jsdoc/grav.sh b/tools/jsdoc/grav.sh deleted file mode 100755 index edd8b6b197..0000000000 --- a/tools/jsdoc/grav.sh +++ /dev/null @@ -1,3 +0,0 @@ -!#/bin/bash -clear -node gravPrep true "/Users/milad/ROLC/Reference/Programming/R_VR/Hifi/hifi-docs-grav/user/themes/learn2/" "/Users/milad/ROLC/Reference/Programming/R_VR/Hifi/hifi-docs-grav-content" \ No newline at end of file diff --git a/tools/jsdoc/gravPrep-Explore.js b/tools/jsdoc/gravPrep-Explore.js deleted file mode 100644 index e0f56de1f2..0000000000 --- a/tools/jsdoc/gravPrep-Explore.js +++ /dev/null @@ -1,493 +0,0 @@ -// Dependencies -const htmlclean = require('htmlclean'); -const fs = require('fs'); -const path = require('path'); -const pretty = require('pretty'); -const cheerio = require('cheerio'); -const rimraf = require('rimraf'); -const dedent = require('dedent-js'); - -// Arg Vars -const copyLocal = process.argv[2]; -console.log("copyLocal:", copyLocal); -let targetTemplateDirectory = '' -let targetMDDirectory = '' -if (copyLocal){ - targetTemplateDirectory = process.argv[3]; - targetMDDirectory = process.argv[4];; -} - -// Required directories -let dir_out = path.join(__dirname, 'out'); - -let dir_grav = path.join(dir_out, 'grav'); -let dir_css = path.join(dir_grav, 'css'); -let dir_js = path.join(dir_grav, 'js'); -let dir_template = path.join(dir_grav, 'templates'); - -let dir_md = path.join(dir_grav, '06.api-reference'); -let dir_md_objects = path.join(dir_md, '02.Objects'); -let dir_md_namespaces = path.join(dir_md, '01.Namespaces'); -let dir_md_globals = path.join(dir_md, '03.Globals'); - -// Array to itterate over and create if doesn't exist -let dirArray = [dir_grav, dir_css, dir_js, dir_template, dir_md, dir_md_objects, dir_md_namespaces, dir_md_globals]; - -// Maps for directory names -let map_dir_md = { - "API-Reference": dir_md, - "Globals": dir_md_globals, - "Objects": dir_md_objects, - "Namespaces": dir_md_namespaces, - "Class": dir_md_objects, - "Namespace": dir_md_namespaces, - "Global": dir_md_globals -} - -// Base Grouping Directories for MD files -let baseMDDirectories = ["API-Reference", "Globals", "Namespaces", "Objects"] - -// Html variables to be handle regex replacements -const html_reg_static = /\(static\)<\/span>/g -const html_reg_title = /\.+?\<\/h1\>/g; -const html_reg_htmlExt = /\.html/g; -const html_reg_objectHeader = /
[\s\S]+?<\/header>/; -const html_reg_objectSpanNew = /

<\/h4>/; -const html_reg_brRemove = /
[\s\S]+?
/; -const html_reg_subsectionEdit = /()([\s\S]*?)(<\/h.>)/g; -const html_reg_subsectionEdit_replace = '

$2

'; -const html_reg_propertiesHeaderEdit = '

Properties:

'; -const html_reg_propertiesHeaderEdit_Replace = '

Properties

'; -const html_reg_typeEdit = /(
Returns[\s\S]*?Type)(<\/dt[\s\S]*?type">)(.*?)(<\/span><\/dd>[\s\S]*?<\/dl>)/g; -const html_reg_typeEdit_replace = '$1: $3' -const html_reg_methodSize = /()(<\/h4>)/g; -const html_reg_methodSize_replace = ''; -const html_reg_typeDefSize = /()/g; -const html_reg_typeDefSize_replace = ''; -const html_reg_returnSize = /
Returns:<\/h5>/g; -const html_reg_returnSize_replace = '
Returns:<\/h6>'; -const html_reg_findByName = '
Methods
`; -const html_reg_findByArticleClose = `` -const html_reg_signalTitle = `

Signals

`; -const html_reg_typeDefinitonsTitle = `

Type Definitions

`; -const html_reg_firstTableClose = ``; - - -// Mapping for GroupNames and Members -let groupNameMemberMap = { - "Objects": [], - "Namespaces": [], - "Globals": [] -} - -// Procedural functions -// Create the actual MD file -function createMD(title, directory, needsDir, isGlobal){ - let mdSource = makeMdSource(title); - - if (needsDir){ - if (!fs.existsSync(directory)) { - fs.mkdirSync(directory); - } - } - - let destinationMDFile = path.join(directory, `API_${title}.md`); - fs.writeFileSync(destinationMDFile, mdSource); -} - -// Create the actual Template file -function createTemplate(title,content){ - let twigBasePartial = makeTwigFile(content); - let destinationFile = path.join(dir_template, `API_${title}.html.twig`); - fs.writeFileSync(destinationFile, twigBasePartial); -} - -// Copy file from source to target - used for recurssive call -function copyFileSync( source, target ) { - let targetFile = target; - - // If target is a directory a new file with the same name will be created - if ( fs.existsSync( target ) ) { - // console.log("target exists"); - if ( fs.lstatSync( target ).isDirectory() ) { - // console.log("target is a directory"); - - targetFile = path.join( target, path.basename( source ) ); - } - } - - fs.writeFileSync(targetFile, fs.readFileSync(source)); -} - -// Copy file from source to target -function copyFolderRecursiveSync( source, target ) { - var files = []; - - // Check if folder needs to be created or integrated - var targetFolder = path.join( target, path.basename( source ) ); - if ( !fs.existsSync( targetFolder ) ) { - fs.mkdirSync( targetFolder ); - } - - // Copy - if ( fs.lstatSync( source ).isDirectory() ) { - files = fs.readdirSync( source ); - files.forEach( function ( file ) { - var curSource = path.join( source, file ); - if ( fs.lstatSync( curSource ).isDirectory() ) { - copyFolderRecursiveSync( curSource, targetFolder ); - } else { - copyFileSync( curSource, targetFolder ); - } - }); - } -} - -// Clean up the Html -function prepareHtml(source){ - let htmlBefore = fs.readFileSync(source, {encoding: 'utf8'}); - let htmlAfter = htmlclean(htmlBefore); - let htmlAfterPretty = pretty(htmlAfter); - return cheerio.load(htmlAfterPretty); -} - -// Base file for MD's -function makeMdSource(title){ - return dedent( - ` - --- - title: ${title} - taxonomy: - category: - - docs - visible: true - --- - ` - ) -} - -// Base file for Templates -function makeTwigFile(contentHtml){ - return dedent( - ` - {% extends 'partials/base_noGit.html.twig' %} - {% set tags = page.taxonomy.tag %} - {% if tags %} - {% set progress = page.collection({'items':{'@taxonomy':{'category': 'docs', 'tag': tags}},'order': {'by': 'default', 'dir': 'asc'}}) %} - {% else %} - {% set progress = page.collection({'items':{'@taxonomy':{'category': 'docs'}},'order': {'by': 'default', 'dir': 'asc'}}) %} - {% endif %} - - {% block navigation %} - - {% endblock %} - - {% block content %} -
-

{{ page.title }}

- ${contentHtml} -
- {% endblock %} - ` - ) -} - -// Handle NameSpace Group -function handleNamespace(title, content){ - groupNameMemberMap["Namespaces"].push(title); - let destinationDirectory = path.join(map_dir_md["Namespace"], title); - createMD(title, destinationDirectory, true); - createTemplate(title, content); -} - -// Handle Class Group -function handleClass(title, content){ - groupNameMemberMap["Objects"].push(title); - let destinationDirectory = path.join(map_dir_md["Class"], title); - createMD(title, destinationDirectory, true) - - let formatedHtml = content - .replace(html_reg_objectSpanNew,"") - createTemplate(title, formatedHtml); -} - -// Handle Global Group -function handleGlobal(title, content){ - groupNameMemberMap["Globals"].push("Globals"); - createMD("Globals", map_dir_md["Global"], false, true); - createTemplate("Globals", content); -} - -// Handle Group TOCs -function makeGroupTOC(group){ - let mappedGroup; - if (!Array.isArray(group)){ - mappedGroup = groupNameMemberMap[group]; - } else { - mappedGroup = group; - } - let htmlGroup = mappedGroup.map( item => { - return dedent( - ` -
- ${item} -
- ` - ) - }) - return htmlGroup.join("\n"); -} - -// Handle Class TOCS -function makeClassTOC(group){ - console.log("group", group) - let linkArray = [] - group.forEach( item => { - linkArray.push(`
${item.type}
`) - item.array.forEach( link => { - if ( link.indexOf('.') > -1 ){ - linkArray.push(``); - } else { - linkArray.push(``); - } - - }) - linkArray.push("
"); - }) - return linkArray.join("\n"); -} - -// Extract IDS for TOC -function extractIDs(groupToExtract){ - let firstLine = ""; - let id = ""; - let extractedIDs = []; - groupToExtract.forEach((item)=>{ - firstLine = item.split("\n")[0]; - try { - id = firstLine.split('id="')[1].split(`"`)[0]; - } catch (e){ - - } - extractedIDs.push(id) - }) - return extractedIDs; -} - -// Helper for splitting up html -// Takes: Content to split, SearchTerm to Split by, and term to End Splitting By -// Returns: [newContent after Split, Array of extracted ] -function splitBy(content, searchTerm, endSplitTerm){ - let foundArray = []; - let curIndex = -1; - let afterCurSearchIndex = -1 - let negateTermIndex = -1; - let nextIndex = 0; - let findbyNameLength = searchTerm.length; - let curfoundArrayIndex = 0; - let curEndSplitTermIndex = -1; - do { - curEndSplitTermIndex = content.indexOf(endSplitTerm); - curIndex = content.indexOf(searchTerm); - afterCurSearchIndex = curIndex+findbyNameLength; - nextIndex = content.indexOf(searchTerm,afterCurSearchIndex); - if (nextIndex === -1){ - nextIndex = curEndSplitTermIndex; - } - foundArray.push(content.slice(curIndex, nextIndex)) - // remove that content - content = content.replace(foundArray[curfoundArrayIndex], ""); - curfoundArrayIndex++; - } while (curIndex > -1) - return [content, foundArray]; -} - -// Split the signals and methods [Might make this more generic] -function splitMethodsSignalsAndTypeDefs(allItemToSplit){ - let methodArray = []; - let signalArray = []; - let typeDefArray = []; - let description; - // console.log(allItemToSplit.length); - allItemToSplit.forEach( content => { - firstLine = content.split("\n")[0]; - if (firstLine.indexOf("Signal") > -1){ - // console.log("Found signal") - signalArray.push(content); - } else if (firstLine.indexOf("span") > -1) { - // console.log("Found method") - if (content.indexOf("Available") > -1){ - console.log("found Available"); - description = content; - } else { - methodArray.push(content); - } - } else { - // console.log("Found typeDef") - if(firstLine.trim() !== ""){ - typeDefArray.push(content); - } - } - }) - return [methodArray, signalArray, typeDefArray, description]; -} - -// Helper to append -// Takes content, the search term to appendTo, the content to append, -// and bool if the append is before the found area -function append(content, searchTermToAppendto, contentToAppend, appendBefore){ - let contentArray = content.split("\n"); - let foundIndex = findArrayTrim(contentArray, searchTermToAppendto) - foundIndex = appendBefore ? foundIndex : foundIndex +1 - - contentArray.splice(foundIndex,0,contentToAppend) - return contentArray.join("\n") -} - -// Helper function for append -function findArrayTrim(array, searchTerm){ - var index = -1; - for (var i = 0; i < array.length; i++){ - index = array[i].trim().indexOf(searchTerm.trim()); - if (index > -1){ - return i - } - } - return index; -} - - -// Remove grav directory if exists to make sure old files aren't kept -if (fs.existsSync(dir_grav)){ - console.log("dir_grav exists"); - rimraf.sync(dir_grav); -} - -// Create Grav directories in JSDOC output -dirArray.forEach(function(dir){ - if (!fs.existsSync(dir)) { - fs.mkdirSync(dir); - } -}) - -// Create baseMD files -baseMDDirectories.forEach( md => { - createMD(md, map_dir_md[md]); -}) - -// Read jsdoc output folder and process html files - let curSource = path.join(dir_out, 'global.html'); - if (path.extname(curSource) == ".html" && path.basename(curSource, '.html') !== "index") { - // Clean up the html source - let loadedHtml = prepareHtml(curSource); - - // Extract the title, group name, and the main div - let splitTitle = loadedHtml("title").text().split(": "); - let groupName = splitTitle[1]; - let htmlTitle = splitTitle.pop(); - let mainDiv = loadedHtml("#main") - - let methodIDs = []; - let signalIDs = []; - let typeDefIDs = []; - // Basic Regex HTML edits - let mainDivRegexed = mainDiv.html() - .replace(html_reg_static,"") - .replace(html_reg_title,"") - .replace(html_reg_objectHeader,"") - .replace(html_reg_htmlExt,"") - .replace(html_reg_brRemove, "") - .replace(html_reg_subsectionEdit, html_reg_subsectionEdit_replace) - .replace(html_reg_propertiesHeaderEdit, html_reg_propertiesHeaderEdit_Replace) - .replace(html_reg_typeEdit, html_reg_typeEdit_replace) - .replace(html_reg_returnSize, html_reg_returnSize_replace) - .replace(html_reg_methodSize, html_reg_methodSize_replace) - .replace(html_reg_typeDefSize, html_reg_typeDefSize_replace) - .replace(html_reg_typeDefinitonsTitle, "") - .replace(html_reg_findByMethod, ""); - fs.writeFileSync(__dirname + "/Examine/global.html", mainDivRegexed); - // Further HTML Manipulation - // Split HTML by Each named entry - let contentSplitArray = splitBy(mainDivRegexed, html_reg_findByName, html_reg_findByArticleClose); - // Create a reference to the current content after split and the split functions - let currentContent = contentSplitArray[0]; - // Create references to the split methods and signals - let processedMethodsSignalsAndTypeDefs = splitMethodsSignalsAndTypeDefs(contentSplitArray[1]); - let splitMethods = processedMethodsSignalsAndTypeDefs[0]; - let splitSignals = processedMethodsSignalsAndTypeDefs[1]; - let splitTypeDefintions = processedMethodsSignalsAndTypeDefs[2]; - let splitDescription = processedMethodsSignalsAndTypeDefs[3]; - let splitMethodIDS = extractIDs(splitMethods); - let splitSignalIDS = extractIDs(splitSignals); - let splitTypeDefinitionIDS = extractIDs(splitTypeDefintions); - let arrayToPassToClassToc = []; - - // Append Signals and Methods to the current Content - if (!splitDescription) { - currentContent = append(currentContent, html_reg_title, splitDescription); - } - if (splitMethods.length > 0) { - arrayToPassToClassToc.push({type: "Methods", array: splitMethodIDS}); - // Add the Signals header to the Signals HTML - splitMethods.unshift(html_reg_findByMethod) - currentContent = append(currentContent, html_reg_findByArticleClose, splitMethods.join('\n'), true); - } - if (splitSignals.length > 0) { - arrayToPassToClassToc.push({type: "Signals", array: splitSignalIDS}); - // Add the Signals header to the Signals HTML - splitSignals.unshift(html_reg_signalTitle) - currentContent = append(currentContent, html_reg_findByArticleClose, splitSignals.join('\n'),true); - } - if (splitTypeDefintions.length > 0) { - - // console.log(path.basename(curSource, '.html')); - // console.log(splitTypeDefintions.length); - arrayToPassToClassToc.push({type: "Type Definitions", array: splitTypeDefinitionIDS}); - // Add the Signals header to the Signals HTML - splitTypeDefintions.unshift(html_reg_typeDefinitonsTitle) - currentContent = append(currentContent, html_reg_findByArticleClose, splitTypeDefintions.join('\n'), true); - } - - let classTOC = makeClassTOC(arrayToPassToClassToc); - currentContent = append(currentContent, html_reg_firstTableClose, classTOC); - - // Final Pretty Content - currentContent = htmlclean(currentContent); - currentContent = pretty(currentContent); - - // Handle Unique Categories - switch(groupName){ - case "Namespace": - handleNamespace(htmlTitle, currentContent); - break; - case "Class": - handleClass(htmlTitle, currentContent); - break; - case "Global": - handleGlobal(htmlTitle, currentContent); - break; - default: - console.log(`Case not handled for ${groupName}`); - } - } - -// Create the base Templates after processing individual files -createTemplate("API-Reference", makeGroupTOC(["Namespaces", "Objects", "Globals"])); -createTemplate("Namespaces", makeGroupTOC("Namespaces")); -createTemplate("Objects", makeGroupTOC("Objects")); - -// Copy the files to the target Directories if Local \ No newline at end of file