refactor(docs): catch some mistakes (#11851)

docs/esdoc-config.js

 'use strict';
 'use strict';
 
 
-const _ = require('lodash');
+const { getDeclaredManuals, checkManuals } = require('./manual-utils');
 
 
-const manualGroups = require('./manual-groups.json');
-
-const manual = {
-  index: './docs/index.md',
-  globalIndex: true,
-  asset: './docs/images',
-  files: _.flatten(_.values(manualGroups)).map(file => `./docs/manual/${file}`)
-};
+checkManuals();
 
 
 module.exports = {
 module.exports = {
   source: './lib',
   source: './lib',
@@ -45,7 +38,12 @@ module.exports = {
           repository: 'https://github.com/sequelize/sequelize',
           repository: 'https://github.com/sequelize/sequelize',
           site: 'https://sequelize.org/master/'
           site: 'https://sequelize.org/master/'
         },
         },
-        manual
+        manual: {
+          index: './docs/index.md',
+          globalIndex: true,
+          asset: './docs/images',
+          files: getDeclaredManuals()
+        }
       }
       }
     }
     }
   ]
   ]

docs/manual-utils.js

+'use strict';
+
+const _ = require('lodash');
+const jetpack = require('fs-jetpack');
+const { normalize } = require('path');
+const assert = require('assert');
+
+function getDeclaredManuals() {
+  const declaredManualGroups = require('./manual-groups.json');
+  return _.flatten(_.values(declaredManualGroups)).map(file => {
+    return normalize(`./docs/manual/${file}`);
+  });
+}
+
+function getAllManuals() {
+  return jetpack.find('./docs/manual/', { matching: '*.md' }).map(m => {
+    return normalize(`./${m}`);
+  });
+}
+
+function checkManuals() {
+  // First we check that declared manuals and all manuals are the same
+  const declared = getDeclaredManuals().sort();
+  const all = getAllManuals().sort();
+  assert.deepStrictEqual(declared, all);
+
+  // Then we check that every manual begins with a single `#`. This is
+  // important for ESDoc to render the left menu correctly.
+  for (const manualRelativePath of all) {
+    assert(
+      /^#[^#]/.test(jetpack.read(manualRelativePath)),
+      `Manual '${manualRelativePath}' must begin with a single '#'`
+    );
+  }
+}
+
+module.exports = { getDeclaredManuals, getAllManuals, checkManuals };
\ No newline at end of file