docs: reorganize files and improve styles (#11405)

.esdoc.json

-{
-  "source": "./lib",
-  "destination": "./esdoc",
-  "includes": ["\\.js$"],
-  "plugins": [
-    {
-      "name": "esdoc-inject-style-plugin",
-      "option": {
-        "enable": true,
-        "styles": [
-          "./docs/css/style.css",
-          "./docs/css/theme.css"
-        ]
-      }
-    },
-    {
-      "name": "esdoc-standard-plugin",
-      "option": {
-        "lint": { "enable": true },
-        "coverage": { "enable": false },
-        "accessor": {
-          "access": ["public"],
-          "autoPrivate": true
-        },
-        "undocumentIdentifier": { "enable": false },
-        "unexportedIdentifier": { "enable": true },
-        "typeInference": { "enable": true },
-        "brand": {
-          "logo": "./docs/images/logo-small.png",
-          "title": "Sequelize",
-          "description": "Node.js ORM for PostgreSQL, MySQL, SQLite and MSSQL",
-          "repository": "https://github.com/sequelize/sequelize",
-          "site": "https://sequelize.org/master/"
-        },
-        "manual": {
-          "index": "./docs/index.md",
-          "globalIndex": true,
-          "asset": "./docs/images",
-          "files": [
-            "./docs/getting-started.md",
-            "./docs/dialects.md",
-            "./docs/data-types.md",
-            "./docs/models-definition.md",
-            "./docs/models-usage.md",
-            "./docs/hooks.md",
-            "./docs/querying.md",
-            "./docs/instances.md",
-            "./docs/associations.md",
-            "./docs/transactions.md",
-            "./docs/scopes.md",
-            "./docs/raw-queries.md",
-            "./docs/read-replication.md",
-            "./docs/migrations.md",
-            "./docs/resources.md",
-            "./docs/typescript.md",
-            "./docs/upgrade-to-v5.md",
-            "./docs/legacy.md",
-            "./docs/whos-using.md",
-            "./docs/legal.md"
-          ]
-        }
-      }
-    },
-    {
-      "name": "./docs/plugins/group-data-types"
-    }
-  ]
-}

docs/css/style.css

@@ -12,24 +12,6 @@ div.sequelize {
   font-family: 'Titillium Web', sans-serif;
 }
 
-a[href="source.html"],
-a[href^="file/lib/"] {
-  display: none;
-}
-
-.slack-logo {
-  height: 20px;
-  position: relative;
-  top: 3px;
-  padding: 0 5px;
-}
-
-.header-logo {
-  height: 25px;
-  position: relative;
-  top: 6px;
-}
-
 .center {
   text-align: center;
 }
@@ -43,4 +25,33 @@ a[href^="file/lib/"] {
   margin-top: 40px !important;
   padding-top: 0;
   height: calc(100% - 40px);
+}
+
+.manual-toc a:hover {
+  color: #999 !important;
+}
+
+.manual-group {
+  font-weight: 600;
+  margin: 9.6px 0 3.2px 0;
+  color: black !important;
+  font-size: 17px;
+}
+
+.api-reference-link {
+  font-weight: bold;
+  padding: 0 20px;
+}
+.api-reference-link:hover {
+  color: rgb(3, 155, 229);
+}
+
+header a {
+  display: flex;
+  align-items: center;
+}
+
+a[href="source.html"],
+a[href^="file/lib/"] {
+  display: none;
 }
\ No newline at end of file

docs/esdoc-config.js

+'use strict';
+
+const _ = require('lodash');
+
+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}`)
+};
+
+module.exports = {
+  source: './lib',
+  destination: './esdoc',
+  includes: ['\\.js$'],
+  plugins: [
+    {
+      name: 'esdoc-inject-style-plugin',
+      option: {
+        enable: true,
+        styles: [
+          './docs/css/style.css',
+          './docs/css/theme.css'
+        ]
+      }
+    },
+    {
+      name: 'esdoc-standard-plugin',
+      option: {
+        lint: { enable: true },
+        coverage: { enable: false },
+        accessor: {
+          access: ['public'],
+          autoPrivate: true
+        },
+        undocumentIdentifier: { enable: false },
+        unexportedIdentifier: { enable: true },
+        typeInference: { enable: true },
+        brand: {
+          logo: './docs/images/logo-small.png',
+          title: 'Sequelize',
+          description: 'An easy-to-use multi SQL dialect ORM for Node.js',
+          repository: 'https://github.com/sequelize/sequelize',
+          site: 'https://sequelize.org/master/'
+        },
+        manual
+      }
+    }
+  ]
+};

docs/index.md

@@ -13,7 +13,6 @@
 [![Last commit](https://badgen.net/github/last-commit/sequelize/sequelize)](https://github.com/sequelize/sequelize)
 [![Merged PRs](https://badgen.net/github/merged-prs/sequelize/sequelize)](https://github.com/sequelize/sequelize)
 [![GitHub stars](https://badgen.net/github/stars/sequelize/sequelize)](https://github.com/sequelize/sequelize)
-[![Bountysource](https://www.bountysource.com/badge/team?team_id=955&style=bounties_received)](https://www.bountysource.com/teams/sequelize/issues?utm_source=Sequelize&utm_medium=shield&utm_campaign=bounties_received)
 [![Slack Status](http://sequelize-slack.herokuapp.com/badge.svg)](http://sequelize-slack.herokuapp.com/)
 [![node](https://badgen.net/npm/node/sequelize)](https://www.npmjs.com/package/sequelize)
 [![License](https://badgen.net/github/license/sequelize/sequelize)](https://github.com/sequelize/sequelize/blob/master/LICENSE)
@@ -30,13 +29,13 @@ You are currently looking at the **Tutorials and Guides** for Sequelize. You mig
 ## Quick example
 
 ```js
-const Sequelize = require('sequelize');
-const sequelize = new Sequelize('postgres://user:pass@example.com:5432/dbname');
+const { Sequelize, Model, DataTypes } = require('sequelize');
+const sequelize = new Sequelize('sqlite::memory:');
 
-class User extends Sequelize.Model {}
+class User extends Model {}
 User.init({
-  username: Sequelize.STRING,
-  birthday: Sequelize.DATE
+  username: DataTypes.STRING,
+  birthday: DataTypes.DATE
 }, { sequelize, modelName: 'user' });
 
 sequelize.sync()

docs/manual-groups.json

+{
+  "Core Concepts": [
+    "getting-started.md",
+    "dialects.md",
+    "data-types.md",
+    "models-definition.md",
+    "models-usage.md",
+    "hooks.md",
+    "querying.md",
+    "instances.md",
+    "associations.md",
+    "raw-queries.md"
+  ],
+  "Other Topics": [
+    "transactions.md",
+    "scopes.md",
+    "read-replication.md",
+    "migrations.md",
+    "resources.md",
+    "typescript.md",
+    "upgrade-to-v5.md",
+    "legacy.md",
+    "whos-using.md",
+    "legal.md"
+  ]
+}
\ No newline at end of file

docs/run-docs-transforms.js

+'use strict';
+
+const jetpack = require('fs-jetpack');
+const cheerio = require('cheerio');
+
+if (jetpack.exists('esdoc') !== 'dir') {
+  throw new Error('./esdoc folder not found.');
+}
+
+const htmlFiles = jetpack.find('./esdoc', { matching: '*.html' });
+const transformFiles = jetpack.find('./docs/transforms', { matching: '*.js' });
+const transforms = transformFiles.map(file => require(jetpack.path('.', file)));
+
+for (const htmlFile of htmlFiles) {
+  console.log(`Transform: ${htmlFile}`);
+  const $ = cheerio.load(jetpack.read(htmlFile));
+  for (const transform of transforms) {
+    transform($, htmlFile);
+  }
+  jetpack.write(htmlFile, $.html());
+}
\ No newline at end of file

docs/plugins/group-data-types.js → docs/transforms/group-data-types.js

 'use strict';
 
-const path = require('path');
-const cheerio = require('cheerio');
-
-function groupDataTypes($) {
+function groupDataTypes($, path) {
   let firstLi;
   $('nav a').each(function() {
     /* eslint-disable no-invalid-this */
@@ -18,20 +15,21 @@ function groupDataTypes($) {
       }
     }
   });
-}
-
-class GroupDataTypesPlugin {
-  onHandleContent(ev) {
-    if (path.extname(ev.data.fileName) !== '.html') return;
-
-    const $ = cheerio.load(ev.data.content);
 
-    groupDataTypes($);
-
-    $('nav li[data-ice=doc]:first-child').css('margin-top', '15px');
-
-    ev.data.content = $.html();
+  if (path.endsWith('identifiers.html')) {
+    const rowsToDelete = [];
+    $('table.summary td a').each(function() {
+      if ($(this).attr('href').startsWith('class/lib/data-types.js~')) {
+        rowsToDelete.push($(this).closest('tr'));
+      }
+    });
+    for (const row of rowsToDelete) {
+      $(row).remove();
+    }
   }
 }
 
-module.exports = new GroupDataTypesPlugin();
\ No newline at end of file
+module.exports = function transform($, path) {
+  groupDataTypes($, path);
+  $('nav li[data-ice=doc]:first-child').css('margin-top', '15px');
+};
\ No newline at end of file

docs/transforms/header-customization.js

+'use strict';
+
+module.exports = function transform($) {
+  const apiReferenceLink = $('header a:nth-child(2)');
+  const githubLogoImage = $('header a img[src="./image/github.png"]');
+
+  apiReferenceLink
+    .text('API Reference')
+    .addClass('api-reference-link');
+
+  githubLogoImage
+    .css('width', '30px')
+    .attr('width', '30px');
+
+  githubLogoImage.closest('a')
+    .css('position', '')
+    .css('top', '')
+    .after(`
+      <a href="http://sequelize-slack.herokuapp.com/">
+        <img src="manual/asset/slack.svg" style="width: 30px" />
+      </a>
+    `);
+};
\ No newline at end of file

docs/transforms/menu-groups.js

+'use strict';
+
+const _ = require('lodash');
+const manualGroups = require('./../manual-groups.json');
+
+module.exports = function transform($) {
+  const listItems = $('nav div.manual-toc-root div[data-ice=manual]');
+
+  $(listItems.get(0)).before(`
+    <div class='manual-group'>
+      <a href='index.html' style='color: black'>Home</a>
+    </div>
+  `);
+
+  let count = 0;
+  _.each(manualGroups, (manuals, groupName) => {
+    $(listItems.get(count)).before(`
+      <div class='manual-group' style='pointer-events: none'>
+        ${groupName}
+      </div>
+    `);
+    count += manuals.length;
+  });
+};
\ No newline at end of file

package.json

@@ -66,6 +66,7 @@
     "eslint": "^6.0.0",
     "eslint-plugin-jsdoc": "^4.1.1",
     "eslint-plugin-mocha": "^5.2.1",
+    "fs-jetpack": "^2.2.2",
     "husky": "^1.3.1",
     "js-combinatorics": "^0.5.4",
     "lcov-result-merger": "^3.0.0",
@@ -121,8 +122,7 @@
     "test-docker": "npm run test-docker-unit && npm run test-docker-integration",
     "test-docker-unit": "npm run test-unit",
     "test-docker-integration": "env-cmd $npm_package_options_env_cmd npm run test-integration",
-    "docs-routing": "cp docs/ROUTER esdoc/ROUTER",
-    "docs": "esdoc && cp docs/favicon.ico esdoc/favicon.ico",
+    "docs": "esdoc -c docs/esdoc-config.js && node docs/run-docs-transforms.js && cp docs/favicon.ico esdoc/favicon.ico && cp docs/ROUTER.txt esdoc/ROUTER",
     "teaser": "node scripts/teaser",
     "test-unit": "mocha --require scripts/mocha-bootload --globals setImmediate,clearImmediate --exit --check-leaks --colors -t 30000 --reporter spec \"test/unit/**/*.js\"",
     "test-unit-mariadb": "cross-env DIALECT=mariadb npm run test-unit",