authorgravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2023-04-15 18:26:20+02:00
committergravatar for kappaloris@gmail.comLoris Cro <kappaloris@gmail.com> 2023-04-15 18:26:53+02:00
logbd3e248c7e943e5f0965391e9a741e7de7526217
tree8759cfbb8a0e455498a450f70b5bd48c8324ad45
parentaa765c1d70443a0495aae9239956683d8a29f823

autodoc: add initial support for linking decls mentioned in markdown

this works both on doc comments and guides

1 files changed, 63 insertions(+), 9 deletions(-)

lib/docs/main.js+63-9
......@@ -2762,7 +2762,7 @@ const NAV_MODES = {
27622762 if (container.src != null) {
27632763 let docs = getAstNode(container.src).docs;
27642764 if (docs != null) {
2765 domTldDocs.innerHTML = markdown(docs);
2765 domTldDocs.innerHTML = markdown(docs, container);
27662766 domTldDocs.classList.remove("hidden");
27672767 }
27682768 }
......@@ -2845,13 +2845,13 @@ const NAV_MODES = {
28452845 docs = docs.trim();
28462846 var short = shortDesc(docs);
28472847 if (short != docs) {
2848 short = markdown(short);
2849 var long = markdown(docs);
2848 short = markdown(short, container);
2849 var long = markdown(docs, container); // TODO: this needs to be the file top lvl struct
28502850 tdDesc.innerHTML =
28512851 "<div class=\"expand\" ><span class=\"button\" onclick=\"toggleExpand(event)\"></span><div class=\"sum-less\">" + short + "</div>" + "<div class=\"sum-more\">" + long + "</div></details>";
28522852 }
28532853 else {
2854 tdDesc.innerHTML = markdown(short);
2854 tdDesc.innerHTML = markdown(short, container);
28552855 }
28562856 } else {
28572857 tdDesc.innerHTML = "<p><i>No documentation provided.</i><p>";
......@@ -3389,7 +3389,7 @@ function addDeclToSearchResults(decl, declIndex, pkgNames, item, list, stack) {
33893389 return markdown(shortDesc(docs));
33903390 }
33913391
3392 function markdown(input) {
3392 function markdown(input, contextType) {
33933393 const raw_lines = input.split("\n"); // zig allows no '\r', so we don't need to split on CR
33943394
33953395 const lines = [];
......@@ -3474,7 +3474,7 @@ function addDeclToSearchResults(decl, declIndex, pkgNames, item, list, stack) {
34743474 // Render HTML from markdown lines.
34753475 // Look at each line and emit fitting HTML code
34763476
3477 function markdownInlines(innerText) {
3477 function markdownInlines(innerText, contextType) {
34783478 // inline types:
34793479 // **{INLINE}** : <strong>
34803480 // __{INLINE}__ : <u>
......@@ -3521,6 +3521,10 @@ function addDeclToSearchResults(decl, declIndex, pkgNames, item, list, stack) {
35213521 let codetag = "";
35223522 let in_code = false;
35233523
3524 // state used to link decl references
3525 let quote_start = undefined;
3526 let quote_start_html = undefined;
3527
35243528 for (let i = 0; i < innerText.length; i++) {
35253529 if (parsing_code && in_code) {
35263530 if (innerText.substr(i, codetag.length) == codetag) {
......@@ -3537,6 +3541,16 @@ function addDeclToSearchResults(decl, declIndex, pkgNames, item, list, stack) {
35373541 parsing_code = false;
35383542 innerHTML += "</code>";
35393543 codetag = "";
3544
3545 // find out if this is a decl that should be linked
3546 const maybe_decl_path = innerText.substr(quote_start, i-quote_start);
3547 const decl_hash = detectDeclPath(maybe_decl_path, contextType);
3548 if (decl_hash) {
3549 const anchor_opening_tag = "<a href='"+ decl_hash +"'>";
3550 innerHTML = innerHTML.slice(0, quote_start_html)
3551 + anchor_opening_tag
3552 + innerHTML.slice(quote_start_html) + "</a>";
3553 }
35403554 } else {
35413555 currentRun += innerText[i];
35423556 }
......@@ -3546,6 +3560,8 @@ function addDeclToSearchResults(decl, declIndex, pkgNames, item, list, stack) {
35463560 if (innerText[i] == "`") {
35473561 flushRun();
35483562 if (!parsing_code) {
3563 quote_start = i + 1;
3564 quote_start_html = innerHTML.length;
35493565 innerHTML += "<code>";
35503566 }
35513567 parsing_code = true;
......@@ -3600,6 +3616,44 @@ function addDeclToSearchResults(decl, declIndex, pkgNames, item, list, stack) {
36003616 return innerHTML;
36013617 }
36023618
3619 function detectDeclPath(text, context) {
3620 let result = "";
3621 let separator = ":";
3622 const components = text.split(".");
3623 let curDeclOrType = undefined;
3624
3625 if (context) {
3626 curDeclOrType = findSubDecl(context, components[0]);
3627 if (curDeclOrType) {
3628 separator = '.';
3629 result = location.hash + separator + components[0];
3630 }
3631 }
3632
3633 if (!curDeclOrType) {
3634 for (let i = 0; i < zigAnalysis.packages.length; i += 1){
3635 const p = zigAnalysis.packages[i];
3636 if (p.name == components[0]) {
3637 curDeclOrType = getType(p.main);
3638 result += "#A;" + components[0];
3639 break;
3640 }
3641 }
3642 }
3643
3644 if (!curDeclOrType) return null;
3645
3646 for (let i = 1; i < components.length; i += 1) {
3647 curDeclOrType = findSubDecl(curDeclOrType, components[i]);
3648 if (!curDeclOrType) return null;
3649 result += separator + components[i];
3650 separator = '.';
3651 }
3652
3653 return result;
3654
3655 }
3656
36033657 function previousLineIs(type, line_no) {
36043658 if (line_no > 0) {
36053659 return lines[line_no - 1].type == type;
......@@ -3647,7 +3701,7 @@ function addDeclToSearchResults(decl, declIndex, pkgNames, item, list, stack) {
36473701 "<" +
36483702 line.type +
36493703 ">" +
3650 markdownInlines(line.text) +
3704 markdownInlines(line.text, contextType) +
36513705 "</" +
36523706 line.type +
36533707 ">\n";
......@@ -3662,7 +3716,7 @@ function addDeclToSearchResults(decl, declIndex, pkgNames, item, list, stack) {
36623716 html += "<" + line.type + ">\n";
36633717 }
36643718
3665 html += "<li>" + markdownInlines(line.text) + "</li>\n";
3719 html += "<li>" + markdownInlines(line.text, contextType) + "</li>\n";
36663720
36673721 if (
36683722 !nextLineIs(line.type, line_no) ||
......@@ -3676,7 +3730,7 @@ function addDeclToSearchResults(decl, declIndex, pkgNames, item, list, stack) {
36763730 if (!previousLineIs("p", line_no)) {
36773731 html += "<p>\n";
36783732 }
3679 html += markdownInlines(line.text) + "\n";
3733 html += markdownInlines(line.text, contextType) + "\n";
36803734 if (!nextLineIs("p", line_no)) {
36813735 html += "</p>\n";
36823736 }