Chore/documentation improvements (#413)

* chore: implement & document a better release process

* chore: changelog generation

* Add HISTORY.md

* Fix jsdoc for debounce

* Add .github_changelog_generator

* chore: configure documentation in order to not require manual tweaks, update graph.config.js

* docs: consolidate the release process

* Change tooltip docs message

Author: danielcaldas

.github_changelog_generator

@@ -0,0 +1,3 @@
+unreleased=true
+future-release=2.6.0
+since-tag=2.5.0

HISTORY.md

@@ -1,25 +1,34 @@
-## Release Process
+# Release Process
 
-This is not yet a full automated process, so here are a few steps to get the thing properly released on github and publish under npm registry.
+Here are the steps to get the thing properly released on GitHub and published under the npm public registry. There's the need of some manual interventions throughout the release process.
 
-### Setup (serve a local version to run tests against it)
+## Requirements
 
-1.  npm run dist:sandbox
-2.  npm run start (server should keep running in the background as we're going to run
-    cypress against it)
+- Make sure you're able to run `react-d3-graph` locally, follow the `Contributions` steps in the `README.md`.
+- Install the [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator) gem locally. The distribution script will use it to automatically generate a changelog (if possible version >=1.15.2).
+- Verify the version: `github_changelog_generator -v`
 
 ### Release steps
 
-1.  Update versioning in package.json
-2.  npm run dist
-3.  npm run docs
-4.  Small tweaks on documentation page (quicklinks)
-5.  Replace current files in docs for the generated ones in gen-docs
-6.  Generate CHANGELOG.md
-    ```bash
-        github_changelog_generator since-tag=<PREVIOUS_RELEASED_VERSION> -u GITHUB_USERNAME
+1.  Update versioning in `package.json`, `package-lock.json` and `.github_changelog_generator`.
+2.  `npm run dist:sandbox` - generates new sandbox assets.
+3.  `npm run start` - server should keep running in the background as we're going to run
+    cypress against it.
+4.  ```bash
+    # https://github.com/github-changelog-generator/github-changelog-generator#github-token
+    export CHANGELOG_GITHUB_TOKEN="«your-40-digit-github-token»"
+    export GITHUB_USERNAME="«your-github-user-name»"
+    export VERSION_PREV=x.x.x
+    export VERSION_NEW=x.x.x
+
+    npm run dist
     ```
-7.  git commit -m "Release x.x.x"
-8.  Create release x.x.x in github
-9.  git pull (origin master)
-10. npm publish
+
+    Please fill in the `VERSION_*` env vars properly to ensure we link documentation during the build process.
+
+5.  `git commit -am "Release x.x.x"`.
+6.  Create the release x.x.x in GitHub. Go to [releases](https://github.com/danielcaldas/react-d3-graph/releases) and click `"Draft a new release"`.
+    1.  Pick a suitable title that highlights some of the most relevant changes.
+    2.  Copy & paste the output of the new CHANGELOG into the release notes.
+7.  Once you're done on GitHub, go back to you terminal and type `git pull origin master` to pull the latest tag.
+8.  `npm publish` (see [npm-publish docs](https://docs.npmjs.com/cli/v6/commands/npm-publish) for more details).

RELEASE_PROCESS.md

@@ -1,15 +1,21 @@
 toc:
   - graph.config
   - Graph
-  - Graph/renderer
-  - Graph/builder
-  - Graph/helper
-  - Graph/collapse-helper
-  - Node
-  - Node/helper
-  - Link
-  - Link/helper
-  - Link/const
-  - Marker
-  - Marker/helper
-  - utils
+  - name: Internal Documentation
+    description: |
+      This section of the documentation is mainly targeted for contributors
+      working on react-d3-graph. If you're looking into making a change into the codebase
+      this section could give you an organized overview on the library modules.
+    children:
+      - Graph/renderer
+      - Graph/builder
+      - Graph/helper
+      - Graph/collapse-helper
+      - Node
+      - Node/helper
+      - Link
+      - Link/helper
+      - Link/const
+      - Marker
+      - Marker/helper
+      - utils

documentation.yml

@@ -11,10 +11,11 @@
     "dist:rd3g": "rm -rf dist/ && webpack --config webpack.config.dist.js -p --display-modules --optimize-minimize",
     "dist:sandbox": "npm run generate:tooltips && webpack --config webpack.config.js -p",
     "dist:transpile": "babel -d lib src",
-    "dist": "npm run check && npm-run-all --parallel dist:*",
+    "dist:docs": "documentation --config documentation.yml build src/**/*.js -f html -o gen-docs && documentation build src/**/*.js -f md > gen-docs/DOCUMENTATION.md",
+    "dist": "npm run check && npm-run-all --parallel dist:* && npm run wrapup:dist",
+    "wrapup:dist": "github_changelog_generator since-tag=$VERSION_PREV -u $GITHUB_USERNAME && mv docs/index.html \"docs/$VERSION_PREV.html\" && mv gen-docs/index.html docs/ && mv gen-docs/DOCUMENTATION.md docs/",
     "docs:lint": "documentation lint src/**/*.js",
     "docs:watch": "documentation --config documentation.yml build src/**/*.js -f html -o gen-docs --watch",
-    "docs": "npm run docs:lint && documentation --config documentation.yml build src/**/*.js -f html -o gen-docs && documentation build src/**/*.js -f md > gen-docs/DOCUMENTATION.md",
     "functional:local": "cross-env CYPRESS_SANDBOX_URL=\"http://localhost:3002\" cypress open",
     "functional:remote": "cross-env CYPRESS_SANDBOX_URL=\"https://danielcaldas.github.io/react-d3-graph/sandbox/index.html\" cypress open",
     "functional": "cross-env CYPRESS_SANDBOX_URL=\"http://127.0.0.1:8888\" cypress run",

package.json

@@ -1,6 +1,13 @@
 /**
  * <div style="text-align: right;"><i>This is certainly the only extra piece of documentation that you will ever need</i></div>
  * </br></br>
+ *
+ * <b>Links</b></br>
+ * <ul>
+ * <li><a href="https://danielcaldas.github.io/react-d3-graph/sandbox/index.html" target="_blank" title="react-d3-graph live demo">🔗 Live Demo</a></li>
+ * <li><a href="https://github.com/danielcaldas/react-d3-graph" target="_blank" title="react-d3-graph repository">🔗 GitHub</a></li>
+ * </ul>
+ *
  * Here you can consult a detailed description of each graph configurable property as well as the default values
  * of those properties.
  *
@@ -102,7 +109,7 @@
  *  - If value is negative, nodes will repel each other. Most of the times this is what we want, so nodes don"t overlap.
  * @param {number} [d3.linkLength=100] - <a id="d3-link-length" href="#d3-link-length">🔗</a> the length of each link from the center of the nodes it joins.
  * @param {number} [d3.linkStrength=1] - <a id="d3-link-strength" href="#d3-link-strength">🔗</a> <a target="_blank" href="https://github.com/d3/d3-force#link_strength">see d3-force link.strength</a>
- * @param {boolean} [d3.disableLinkForce=false] - <a id="d3-disable-link-force" href="#d3-disable-link-force">🔗</a> ⚠️🧪EXPERIMENTAL🧪⚠️ it completely disables d3 force link and simulation to re-trigger so that one can obtain
+ * @param {boolean} [d3.disableLinkForce=false] - <a id="d3-disable-link-force" href="#d3-disable-link-force">🔗</a> Completely disables d3 force link and simulation to re-trigger so that one can obtain
  * precise render of node positions as described by the author <a target="_blank" href="https://github.com/antoninklopp">@antoninklopp</a> in <a target="_blank" href="https://github.com/danielcaldas/react-d3-graph/pull/278">the Pull Request description</a>.
  * </br>
  * @param {Object} node node object is explained in next section. ⬇️
@@ -213,7 +220,7 @@
  * property for when link is mouse hovered.
  * @param {number} [link.opacity=1] 🔍 - <a href="#link-opacity" href="">🔗</a> the default opacity value for links.
  * @param {boolean} [link.renderLabel=false] - <a id="link-render-label" href="#link-render-label">🔗</a> when set to true labels will appear along side links in the
- * graph. <b>Note</b>: this will only happen of course if proper label is passed within the link, check also <code>link.labelProperty</code>.
+ * graph. <b>Note:</b> this will only happen of course if proper label is passed within the link, check also <code>link.labelProperty</code>.
  * </br>
  * <img src="https://github.com/danielcaldas/react-d3-graph/blob/master/docs/rd3g-link-render-label.png?raw=true" width="820" height="480"/>
  * @param {boolean} [link.semanticStrokeWidth=false] - <a id="link-semantic-stroke-width" href="#link-semantic-stroke-width">🔗</a> when set to true all links will have

src/components/graph/graph.config.js

@@ -177,6 +177,7 @@ function antiPick(o, props = []) {
  * @param {function} fn Function to debounce
  * @param {number} time Milliseconds to wait before invoking the function if it is called repeatedly
  * @returns {function} Version of function that will only be called every `time` milliseconds
+ * @memberof utils
  */
 function debounce(fn, time) {
   let timer;

src/utils.js

@@ -3,7 +3,7 @@ const TOOLTIPS_MAX_WIDTH = 400;
 const LIVE_DOCS_LINK = "https://danielcaldas.github.io/react-d3-graph/docs/index.html";
 
 if (!data || !data.length || !data[0].params) {
-    throw new Error("Invalid JSON provided from jsdoc parser");
+  throw new Error("Invalid JSON provided from jsdoc parser");
 }
 
 /**
@@ -12,12 +12,12 @@ if (!data || !data.length || !data[0].params) {
  * @returns {string} new string which results on converting input string to kebab case.
  */
 function strToKebabCase(s) {
-    const _s = s.replace(".", "-"); // drop all the '.' dots
+  const _s = s.replace(".", "-"); // drop all the '.' dots
 
-    return _s
-        .replace(/([a-z])([A-Z])/g, "$1-$2")
-        .replace(/\s+/g, "-")
-        .toLowerCase();
+  return _s
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .replace(/\s+/g, "-")
+    .toLowerCase();
 }
 
 /**
@@ -27,9 +27,9 @@ function strToKebabCase(s) {
  * official documentation website.
  */
 function generatePropertyAnchorLink(name) {
-    const suffix = strToKebabCase(name);
+  const suffix = strToKebabCase(name);
 
-    return `${LIVE_DOCS_LINK}#${suffix}`;
+  return `${LIVE_DOCS_LINK}#${suffix}`;
 }
 
 /**
@@ -38,11 +38,11 @@ function generatePropertyAnchorLink(name) {
  * @returns {string} the footer for the given property.
  */
 function generateCommonFooter(name) {
-    const href = generatePropertyAnchorLink(name);
+  const href = generatePropertyAnchorLink(name);
 
-    return `\
+  return `\
         <small>\
-            for more details check the <a target="_blank" href="${href}">official documentation</a>\
+          <a target="_blank" href="${href}">see full official documentation</a>\
         </small>\
     `;
 }
@@ -68,25 +68,25 @@ function generateCommonFooter(name) {
  * information mapped by the param name.
  */
 function getParamInfo(param) {
-    const { type, optional, defaultvalue, description: rawDescription, name } = param;
-    const types = type && type.names && type.names;
-    const ftype = types && types.length ? types.join("|") : "*";
+  const { type, optional, defaultvalue, description: rawDescription, name } = param;
+  const types = type && type.names && type.names;
+  const ftype = types && types.length ? types.join("|") : "*";
 
-    // make images smaller so that they fit in the tooltip
-    const description = rawDescription
-        .replace(/width="(\d+)"/gi, "width='400'")
-        .replace(/height="(\d+)"/gi, "height='200'")
-        .replace("🔗", ""); // drop docs anchor links
+  // make images smaller so that they fit in the tooltip
+  const description = rawDescription
+    .replace(/width="(\d+)"/gi, "width='400'")
+    .replace(/height="(\d+)"/gi, "height='200'")
+    .replace("🔗", ""); // drop docs anchor links
 
-    return {
-        [name]: `\
+  return {
+    [name]: `\
             <h4>${name}</h4>\
             <b>type</b>: ${ftype} | <b>default value</b>: ${defaultvalue} | <b>optional</b>: ${optional}\
             <h5>Description</h5>\
             <div style="max-width: ${TOOLTIPS_MAX_WIDTH}px;">${description}</div>\
             ${generateCommonFooter(name)}\
         `,
-    };
+  };
 }
 
 /**
@@ -96,7 +96,7 @@ function getParamInfo(param) {
  * @returns {string} final text without javascript code blocks.
  */
 function stripJsMdBlocks(s) {
-    return s.replace(/```javascript(.*)```/gi, "");
+  return s.replace(/```javascript(.*)```/gi, "");
 }
 
 const graphConfigElms = data[0].params.map(getParamInfo).reduce((acc, o) => ({ ...o, ...acc }), {});