Now add links when a built-in function is referenced inside backticks

Author: gfwilliams

scripts/build_docs.py

@@ -41,7 +41,7 @@
 
 jsondatas = common.get_jsondata(True)
 
-classes = []
+classes = [] # list of class names
 libraries = []
 for jsondata in jsondatas:
   if "class" in jsondata:
@@ -68,27 +68,31 @@
 htmlFile = open('functions.html', 'w')
 def html(s): htmlFile.write(s+"\n");
 
-def htmlify(d):
+def htmlify(d,current):
   d = markdown.markdown(d, extensions=['urlize'])
   # replace <code> with newlines with pre
   idx = d.find("<code>")
   end = d.find("</code>", idx)
   while idx>=0 and end>idx:
-    codeBlock = d[idx:end+7]
+    codeBlock = d[idx+6:end]
+    # search for known links in code
+    if codeBlock[-2:]=="()" and codeBlock[:-2] in links:
+      codeBlock = "<a href=\"#"+links[codeBlock[:-2]]+"\">"+codeBlock+"</a>";
+    elif codeBlock in links:
+      codeBlock = "<a href=\"#"+links[codeBlock]+"\">"+codeBlock+"</a>";
+    # ensure multi-line code is handled correctly
+    codeBlock = "<code>"+codeBlock+"</code>";
     if codeBlock.find("\n")>=0:
-      d = d[0:idx]+"<pre>"+codeBlock+"</pre>"+d[end+7:];
-    idx = d.find("<code>", end+7+5+6)
+      codeBlock = "<pre>"+codeBlock+"</pre>"
+    d = d[0:idx]+codeBlock+d[end+7:];
+    # search again
+    idx = d.find("<code>", end)
     end = d.find("</code>", idx)
   return d;
 
 def html_description(d,current):
   if isinstance(d, list): d = "\n".join(d)
-  d = htmlify(d)
-  for link in links:
-    if link!=current:
-      d = d.replace(" "+link+" ", " <a href=\"#"+links[link]+"\">"+link+"</a> ")
-      d = d.replace(" "+link+".", " <a href=\"#"+links[link]+"\">"+link+"</a>.")
-      d = d.replace(" "+link+"(", " <a href=\"#"+links[link]+"\">"+link+"</a>(")
+  d = htmlify(d,current)
   html("<div class=\"description\">\n" + d + "\n</div>\n")
 
 def get_prefixed_name(jsondata):
@@ -241,6 +245,11 @@ def insert_mdn_link(jsondata):
 
 detail = []
 links = {}
+def add_link(jsondata):
+  if not "no_create_links" in jsondata:
+    link = get_prefixed_name(jsondata);
+    if link!="global":
+      links[link] = get_link(jsondata)
 jsondatas = sorted(jsondatas, key=lambda s: common.get_name_or_space(s).lower())
 
 html('  <div id="contents">')
@@ -249,17 +258,13 @@ def insert_mdn_link(jsondata):
 html("  <li><a class=\"blush\" name=\"t__global\" href=\"#_global\" onclick=\"place('_global');\">Globals</A></li>")
 for jsondata in jsondatas:
   if "name" in jsondata and not "class" in jsondata:
-    link = get_link(jsondata)
-    if not "no_create_links" in jsondata:
-      links[get_prefixed_name(jsondata)] = link
+    add_link(jsondata)
     detail.append(jsondata)
 for className in sorted(classes, key=lambda s: s.lower()):
   html("  <li><a class=\"blush\" name=\"t_"+className+"\" href=\"#"+className+"\" onclick=\"place('"+className+"');\">"+className+"</a></li>")
   for jsondata in jsondatas:
     if "name" in jsondata and "class" in jsondata and jsondata["class"]==className:
-      link = get_link(jsondata)
-      if not "no_create_links" in jsondata:
-        links[get_prefixed_name(jsondata)] = link
+      add_link(jsondata)
       detail.append(jsondata)
 html("  </ul>")
 html('  </div><!-- Contents -->')
@@ -313,7 +318,7 @@ def insert_mdn_link(jsondata):
     html("  </ul>")
   link = get_link(jsondata)
   html("  <h3 class=\"detail\"><a class=\"blush\" name=\""+link+"\" href=\"#t_"+link+"\" onclick=\"place('t_"+link+"','"+linkName+"');\">"+get_fullname(jsondata)+"</a>")
-  html("<!-- "+json.dumps(jsondata, sort_keys=True, indent=2)+"-->");
+  #html("<!-- "+json.dumps(jsondata, sort_keys=True, indent=2)+"-->");
   if "githublink" in jsondata:
     html('<a class="githublink" title="Link to source code on GitHub" href="'+jsondata["githublink"]+'">&rArr;</a>');
   html("</h3>")
@@ -346,13 +351,13 @@ def insert_mdn_link(jsondata):
       if isinstance(desc, list): desc = '<br/>'.join(desc)
       extra = ""
       if  param[1]=="JsVarArray": extra = ", ...";
-      html("   <div class=\"param\">"+htmlify("`"+param[0]+extra+"` - "+desc)+"</div>")
+      html("   <div class=\"param\">"+htmlify("`"+param[0]+extra+"` - "+desc,"")+"</div>")
   if "return" in jsondata:
     html("  <h4>Returns</h4>")
     desc = ""
     if len(jsondata["return"])>1: desc=jsondata["return"][1]
     if desc=="": desc="See description above"
-    html("   <div class=\"return\">"+htmlify(desc)+"</div>")
+    html("   <div class=\"return\">"+htmlify(desc,"")+"</div>")
 
   url = "http://www.espruino.com/Reference#"+get_link(jsondata)
   if url in code_uses:

src/jswrap_interactive.c

@@ -328,7 +328,7 @@ void jswrap_interface_edit(JsVar *funcName) {
     ["echoOn","bool",""]
   ]
 }
-Should TinyJS echo what you type back to you? true = yes (Default), false = no. When echo is off, the result of executing a command is not returned. Instead, you must use 'print' to send output.
+Should Espruino echo what you type back to you? true = yes (Default), false = no. When echo is off, the result of executing a command is not returned. Instead, you must use 'print' to send output.
  */
 void jswrap_interface_echo(bool echoOn) {
   if (echoOn)
@@ -511,7 +511,7 @@ JsVar *jswrap_interface_setTimeout(JsVar *func, JsVarFloat timeout, JsVar *args)
     ["id","JsVar","The id returned by a previous call to setInterval"]
   ]
 }
-Clear the Interval that was created with setInterval, for example:
+Clear the Interval that was created with `setInterval`, for example:
 
 ```var id = setInterval(function () { print('foo'); }, 1000);```
 
@@ -527,7 +527,7 @@ If no argument is supplied, all timers and intervals are stopped
     ["id","JsVar","The id returned by a previous call to setTimeout"]
   ]
 }
-Clear the Timeout that was created with setTimeout, for example:
+Clear the Timeout that was created with `setTimeout`, for example:
 
 ```var id = setTimeout(function () { print('foo'); }, 1000);```
 
@@ -584,7 +584,7 @@ void jswrap_interface_clearTimeout(JsVar *idVar) {
     ["time","float","The new time period in ms"]
   ]
 }
-Change the Interval on a callback created with setInterval, for example:
+Change the Interval on a callback created with `setInterval`, for example:
 
 ```var id = setInterval(function () { print('foo'); }, 1000); // every second```
 

src/jswrap_serial.c

@@ -162,14 +162,14 @@ The sixth Serial (USART) port
   "name" : "LoopbackA",
   "instanceof" : "Serial"
 }
-A loopback serial device. Data sent to LoopbackA comes out of LoopbackB and vice versa
+A loopback serial device. Data sent to `LoopbackA` comes out of `LoopbackB` and vice versa
  */
 /*JSON{
   "type" : "object",
   "name" : "LoopbackB",
   "instanceof" : "Serial"
 }
-A loopback serial device. Data sent to LoopbackA comes out of LoopbackB and vice versa
+A loopback serial device. Data sent to `LoopbackA` comes out of `LoopbackB` and vice versa
  */
 /*JSON{
   "type" : "object",
@@ -245,7 +245,7 @@ pin's value will be 0 when Espruino is ready for data and 1 when it isn't.
 By default, framing or parity errors don't create `framing` or `parity` events
 on the `Serial` object because storing these errors uses up additional
 storage in the queue. If you're intending to receive a lot of malformed
-data then the queue mioght overflow `E.getErrorFlags()` would return `FIFO_FULL`.
+data then the queue might overflow `E.getErrorFlags()` would return `FIFO_FULL`.
 However if you need to respond to `framing` or `parity` errors then 
 you'll need to use `errors:true` when initialising serial.
 */