tools: create HTML docs with unified/remark/rehype

PR-URL: #21490
Reviewed-By: Vse Mozhet Byt <[email protected]>
Reviewed-By: Rich Trott <[email protected]>

Author: rubys

LICENSE

@@ -1197,6 +1197,57 @@ The externally maintained libraries used by Node.js are:
     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
   """
 
+- unified, located at deps/unified, is licensed as follows:
+  """
+    (The MIT License)
+
+    Copyright (c) 2015 Titus Wormer <[email protected]>
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.
+  """
+
+- remark-rehype, located at deps/remark-rehype, is licensed as follows:
+  """
+    (The MIT License)
+
+    Copyright (c) 2016 Titus Wormer <[email protected]>
+
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    'Software'), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+  """
+
 - remark-cli, located at tools/remark-cli, is licensed as follows:
   """
     (The MIT License)

Makefile

@@ -266,7 +266,6 @@ test: all ## Runs default tests, linters, and builds docs.
 	# can be displayed together
 	$(MAKE) -s build-addons
 	$(MAKE) -s build-addons-napi
-	$(MAKE) -s test-doc
 	$(MAKE) -s cctest
 	$(MAKE) -s jstest
 
@@ -618,7 +617,8 @@ apidocs_json = $(addprefix out/,$(apidoc_sources:.md=.json))
 apiassets = $(subst api_assets,api/assets,$(addprefix out/,$(wildcard doc/api_assets/*)))
 
 .PHONY: doc-only
-doc-only: $(apidoc_dirs) $(apiassets)  ## Builds the docs with the local or the global Node.js binary.
+doc-only: tools/doc/node_modules \
+	$(apidoc_dirs) $(apiassets)  ## Builds the docs with the local or the global Node.js binary.
 # If it's a source tarball, assets are already in doc/api/assets,
 # no need to install anything, we have already copied the docs over
 	if [ ! -d doc/api/assets ]; then \
@@ -1089,8 +1089,13 @@ tools/remark-preset-lint-node/node_modules: \
 
 .PHONY: lint-md-build
 lint-md-build: tools/remark-cli/node_modules \
+	tools/doc/node_modules \
 	tools/remark-preset-lint-node/node_modules
 
+.PHONY: tools/doc/node_modules
+tools/doc/node_modules:
+	@cd tools/doc && $(call available-node,$(run-npm-install))
+
 .PHONY: lint-md
 ifneq ("","$(wildcard tools/remark-cli/node_modules/)")
 

test/doctool/test-doctool-html.js

@@ -21,8 +21,8 @@ const toHTML = require('../../tools/doc/html.js');
 const testData = [
   {
     file: fixtures.path('sample_document.md'),
-    html: '<ol><li>fish</li><li><p>fish</p></li><li><p>Redfish</p></li>' +
-      '<li>Bluefish</li></ol>'
+    html: '<ol><li>fish</li><li>fish</li></ol>' +
+      '<ul><li>Redfish</li><li>Bluefish</li></ul>'
   },
   {
     file: fixtures.path('order_of_end_tags_5873.md'),
@@ -31,7 +31,7 @@ const testData = [
       'id="foo_class_method_buffer_from_array">#</a> </span> </h3>' +
       '<ul><li><code>array</code><a ' +
       'href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/' +
-      'Reference/Global_Objects/Array" class="type">&lt;Array&gt;</a></li></ul>'
+      'Reference/Global_Objects/Array" class="type">&#x3C;Array></a></li></ul>'
   },
   {
     file: fixtures.path('doc_with_yaml.md'),
@@ -45,11 +45,11 @@ const testData = [
       '<h2>Foobar II<span><a class="mark" href="#foo_foobar_ii" ' +
       'id="foo_foobar_ii">#</a></span></h2><div class="api_metadata">' +
       '<details class="changelog"><summary>History</summary>' +
-      '<table><tr><th>Version</th><th>Changes</th></tr>' +
+      '<table><tbody><tr><th>Version</th><th>Changes</th></tr>' +
       '<tr><td>v5.3.0, v4.2.0</td>' +
       '<td><p><span>Added in: v5.3.0, v4.2.0</span></p></td></tr>' +
       '<tr><td>v4.2.0</td><td><p>The <code>error</code> parameter can now be' +
-      'an arrow function.</p></td></tr></table></details></div> ' +
+      'an arrow function.</p></td></tr></tbody></table></details></div> ' +
       '<p>Describe <code>Foobar II</code> in more detail here.' +
       '<a href="http://man7.org/linux/man-pages/man1/fg.1.html"><code>fg(1)' +
       '</code></a></p><h2>Deprecated thingy<span><a class="mark" ' +
@@ -65,8 +65,8 @@ const testData = [
   },
   {
     file: fixtures.path('sample_document.md'),
-    html: '<ol><li>fish</li><li><p>fish</p></li><li><p>Redfish</p></li>' +
-      '<li>Bluefish</li></ol>',
+    html: '<ol><li>fish</li><li>fish</li></ol>' +
+      '<ul><li>Red fish</li><li>Blue fish</li></ul>',
     analyticsId: 'UA-67020396-1'
   },
 ];