adapt-authoring-docs 1.1.1 → 1.2.0

package/bin/docgen.js

@@ -17,8 +17,11 @@ process.env.ADAPT_AUTHORING_LOGGER__mute = !DEBUG
 const app = App.instance
 let outputdir
 
-let manualIndex // populated in cacheConfigs
-let sourceIndex // populated in cacheConfigs
+const defaultPages = { // populated in cacheConfigs
+  manualCover: undefined,
+  manualIndex: undefined,
+  sourceIndex: undefined
+}
 /**
 * Caches loaded JSON so we don't load multiple times.
 * Documentation for a module can be enabled in:
@@ -36,14 +39,12 @@ function cacheConfigs () {
     else if (excludes.includes(dep.name)) omitMsg = 'module has been excluded in documentation config'
     if (omitMsg) return console.log(`Omitting ${dep.name}, ${omitMsg}`)
 
-    if (c.manualIndex) {
-      if (manualIndex) return console.log(`${dep.name}: manualIndex has been specified by another module as ${manualIndex}`)
-      manualIndex = path.join(dep.rootDir, c.manualIndex).split(path.sep).join(path.posix.sep)
-    }
-    if (c.sourceIndex) {
-      if (sourceIndex) return console.log(`${dep.name}: sourceIndex has been specified by another module as ${sourceIndex}`)
-      sourceIndex = path.join(dep.rootDir, c.sourceIndex).split(path.sep).join(path.posix.sep)
-    }
+    Object.keys(defaultPages).forEach(p => {
+      if (!c[p]) return
+      if (defaultPages[p]) return console.log(`${dep.name}: ${p} has been specified by another module as ${defaultPages[p]}`)
+      defaultPages[p] = path.join(dep.rootDir, c[p]).split(path.sep).join(path.posix.sep)
+    })
+
     cache.push({
       ...c,
       name: dep.name,
@@ -90,8 +91,8 @@ async function docs () {
     await fs.rm(outputdir, { recursive: true, force: true })
     await fs.mkdir(outputdir)
     await copyRootFiles()
-    await jsdoc3(app, cachedConfigs, outputdir, sourceIndex)
-    await docsify(app, cachedConfigs, outputdir, manualIndex, sourceIndex)
+    await jsdoc3(app, cachedConfigs, outputdir, defaultPages)
+    await docsify(app, cachedConfigs, outputdir, defaultPages)
     await swagger(app, cachedConfigs, outputdir)
   } catch (e) {
     console.log(e)

package/bin/docserve.js

@@ -36,7 +36,7 @@ App.instance.onReady().then(async app => {
   const PORT = 9000
   const OPEN = process.argv.some(a => a === '--open')
 
-  const server = http.createServer({ root: ROOT, port: PORT })
+  const server = http.createServer({ root: ROOT, cache: -1 })
 
   server.listen(PORT, () => {
     const url = `http://localhost:${PORT}`

package/conf/config.schema.json

@@ -12,29 +12,14 @@
       "description": "Sections for categorising documentation manual pages",
       "type": "object",
       "default": {
-        "getting-started": {
-          "title": "Getting started"
-        },
-        "basics": {
-          "title": "The basics"
-        },
-        "advanced": {
-          "title": "Advanced topics"
-        },
-        "ui": {
-          "title": "Front-end app"
-        },
-        "other-guides": {
-          "title": "Other guides",
-          "default": true
-        },
-        "contributing": {
-          "title": "Contributing"
-        },
-        "reference": {
-          "title": "Reference"
-        }
+        "getting-started": {},
+        "concepts": {},
+        "development": {},
+        "documentation": {},
+        "contributing": {},
+        "reference": {},
+        "other-guides": { "default": true }
       }
     }
   }
-}
+}

package/docsify/docsify.js

@@ -12,10 +12,15 @@ function resolvePath (relativePath) {
   return fileURLToPath(new URL(relativePath, import.meta.url))
 }
 
+// Capitalise and convert dashes to spaces
+function generateSectionTitle (sectionName) {
+  return sectionName[0].toUpperCase() + sectionName.slice(1).replaceAll('-', ' ')
+}
+
 /**
  * Copies all doc files ready for the generator
  */
-export default async function docsify (app, configs, outputdir, manualIndex, sourceIndex) {
+export default async function docsify (app, configs, outputdir, defaultPages) {
   const dir = path.resolve(outputdir, 'manual')
   const sectionsConf = app.config.get('adapt-authoring-docs.manualSections')
   const defaultSection = Object.entries(sectionsConf).reduce((m, [id, data]) => data.default ? id : m)
@@ -52,13 +57,14 @@ export default async function docsify (app, configs, outputdir, manualIndex, sou
       })
     }
     [...customFiles, ...globSync('docs/*.md', { cwd: c.rootDir, absolute: true })].forEach(f => {
-      if (f === sourceIndex) {
+      if (f === defaultPages.sourceIndex) {
         return
       }
       const title = path.basename(f)
-      const sectionName = c.manualPages && c.manualPages[title] ? c.manualPages[title] : defaultSection
+      const sectionName = c.manualPages?.[title] ?? defaultSection
 
       if (!sectionsConf[sectionName]) sectionsConf[sectionName] = {}
+      if (!sectionsConf[sectionName].title) sectionsConf[sectionName].title = generateSectionTitle(sectionName)
       if (!sectionsConf[sectionName].pages) sectionsConf[sectionName].pages = []
 
       sectionsConf[sectionName].pages.push(title)
@@ -69,6 +75,19 @@ export default async function docsify (app, configs, outputdir, manualIndex, sou
       } catch (e) {}
     })
   }))
+  /**
+   * Set options
+   */
+  const options = {
+    name: '<img class="logo" src="assets/logo-outline-colour.png" />Adapt authoring tool<h2>Developer guides</h2>',
+    repo: 'https://github.com/adapt-security/adapt-authoring',
+    themeColor: '#36cde8',
+    loadSidebar: true,
+    loadNavbar: false,
+    autoHeader: true,
+    coverpage: false,
+    homepage: false
+  }
   /**
    * Copy files
    */
@@ -76,20 +95,30 @@ export default async function docsify (app, configs, outputdir, manualIndex, sou
   await fs.copy(resolvePath('../assets'), `${dir}/assets`)
   await fs.copy(resolvePath('./js'), `${dir}/js`)
   await fs.copy(resolvePath('./styles'), `${dir}/styles`)
-  if (manualIndex) {
-    await fs.copy(manualIndex, `${dir}/_coverpage.md`)
+
+  if (defaultPages.manualCover) {
+    await fs.copy(defaultPages.manualCover, `${dir}/cover.md`)
+    options.coverpage = 'cover.md'
+    delete titleMap[path.basename(defaultPages.manualCover)]
+  }
+  if (defaultPages.manualIndex) {
+    await fs.copy(defaultPages.manualIndex, `${dir}/home.md`)
+    options.homepage = 'home.md'
+    delete titleMap[path.basename(defaultPages.manualIndex)]
   }
+  // add Docsify options
+  const f = `${dir}/js/adapt.js`
+  const s = (await fs.readFile(f)).toString()
+  await fs.writeFile(f, s.replace('OPTIONS', JSON.stringify(options)))
+
   await Promise.allSettled(Object.entries(titleMap).map(([filename, v]) => fs.copy(v.path, `${dir}/${filename}`)))
   /**
    * Generate custom sidebar
    */
-  let sidebarMd = ''
+  let sidebarMd = '<ul class="intro"><li><a href="#/" title="Introduction">Introduction</a></li></ul>'
   Object.entries(sectionsConf)
     .forEach(([id, { title, pages = [] }]) => {
-      const filtered = pages.filter(f => {
-        const p = titleMap[f].path
-        return p !== manualIndex && p !== sourceIndex
-      })
+      const filtered = pages.filter(f => titleMap[f]?.path)
       if (!filtered || !filtered.length) {
         return
       }

package/docsify/js/adapt.js

@@ -1,14 +1,8 @@
 /* global addEventListener localStorage */
 
-window.$docsify = {
-  name: '<img class="logo" src="assets/logo-outline-colour.png" />Adapt authoring tool<h2>Developer guides</h2>',
-  repo: 'https://github.com/adapt-security/adapt-authoring',
-  themeColor: '#36cde8',
-  loadSidebar: true,
-  loadNavbar: false,
-  autoHeader: true,
-  coverpage: true
-}
+// options dynamically populated in docsify.js
+window.$docsify = OPTIONS
+/* global OPTIONS */
 
 function onLoad () {
   updateTheme()

package/docsify/styles/adapt.css

@@ -27,6 +27,12 @@ h1 > a, h2 > a, h3 > a, h4 > a, h5 > a, h6 > a {
   font-weight: 300 !important;
 }
 
+.big-text {
+  font-size: 35px;
+  margin: 50px 0;
+  text-align: center;
+}
+
 summary {
   font-size: 1.15rem;
   cursor: pointer;
@@ -83,6 +89,13 @@ section.cover .cover-main > p:last-child a:hover,
   font-weight: normal;
   font-size: 14px;
 }
+.sidebar ul.intro li {
+  margin-left: 0
+}
+.sidebar ul.intro li a {
+  font-size: 18px;
+  text-decoration: underline;
+}
 .sidebar ul.header {
   padding-top: 20px;
   padding-bottom: 5px;

package/jsdoc3/jsdoc3.js

@@ -88,10 +88,10 @@ function getSourceIncludes (indexFile) {
   return includes
 }
 
-export default async function jsdoc3 (app, configs, outputdir, sourceIndexFile) {
+export default async function jsdoc3 (app, configs, outputdir, defaultPages) {
   cachedConfigs = configs
   const dir = `${outputdir}/backend`
-  await writeConfig(app, dir, sourceIndexFile)
+  await writeConfig(app, dir, defaultPages.sourceIndex)
   try {
     await execPromise(`npx jsdoc -c ${configPath}`)
   } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "adapt-authoring-docs",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Tools for auto-generating documentation for the Adapt authoring tool",
   "homepage": "https://github.com/adapt-security/adapt-authoring-docs",
   "license": "GPL-3.0",