Nim: [docgen] Make the link text in the sidebar more descriptive.. add proc signature too

[kaushalmodi]

For example: https://nim-lang.org/docs/system.html

While scrolling through the sidebar, you see:

The links to high, low, etc are not much useful. It would be better to include the signatures in there too. It will become a lot more verbose, but more useful too.

Or.. may be just collapse all high links into a single link pointing to the first of the high procs, and so on.

[awr1]

Or.. may be just collapse all high links into a single link pointing to the first of the high procs, and so on.

Contingent on that the declarations/definitions are made in the correct order, I'm assuming? So that:

proc high..
proc low...
proc blah...
proc high...
proc low...

laid out in the nim file in that manner wouldn't collapse in the docs? (Or should there be some type of reordering involved?)

[kaushalmodi]

@awr1 I would certainly prefer having the signatures next to the proc names in the sidebar too.

Collapsing all proc variants is just a last resort thing.

[awr1]

If we do that, instead of having the parameters on the same line, I think we should have it below each name in smaller, grayed out text, like so:

[kaushalmodi]

@awr1 I think that looks great! Why don't you submit a PR?

[ghost]

Here is some JavaScript that improves it marginally:

~~~js
let list_top = document.querySelectorAll('.reference-toplevel');
let list_old;

for (let e1 of list_top) {
if (e1.textContent == 'Procs') {
list_old = e1.parentNode.querySelector('.simple-toc-section');
break;
}
}

let a_old = list_old.querySelectorAll('a');
let list_new = [];

for (let e1 of a_old) {
list_new.push([e1.title, e1.href]);
}

list_new.sort();
let n_max = 33;

for (let a1 of list_new) {
let a_new = document.createElement('a');
let p_new = document.createElement('p');
if (a1[0].length > n_max) {
a_new.textContent = a1[0].substring(0, n_max) + '…';
} else {
a_new.textContent = a1[0];
}
a_new.href = a1[1];
p_new.append(a_new);
list_old.parentNode.append(p_new);
}

list_old.remove();
document.querySelector('.nine.columns').style.width = '74%';
document.querySelector('.three.columns').style.width = '25%';
~~~

[kaushalmodi]

@cup Would it be possible to bake that into the JS that runs on the Nim doc site and submit that as a PR?

[ghost]

@kaushalmodi better would be to modify the code that actually generates the site. In general, server side is better than client side. If someone can point me to where that code is, I can look into it.

[narimiran]

If someone can point me to where that code is, I can look into it.

This part of rstgen.nim seems to be what you're looking for.

[ghost]

@narimiran ok I dont think thats quite right. If you look here:

https://nim-lang.github.io/Nim/os

The links look like this:

~html
title="joinPath(head, tail: string): string">joinPath class="attachedType">
~

but the code you point to look like this:

https://github.com/nim-lang/Nim/blob/21ea1094ef0de2e0661835f9f8b56fa0b9eb4d17/lib/packages/docutils/rstgen.nim#L774-L777

Notice that the important attribute title is missing. Proper locations would
be:

https://github.com/nim-lang/Nim/blob/21ea1094ef0de2e0661835f9f8b56fa0b9eb4d17/lib/packages/docutils/rstgen.nim#L1270-L1273

and:

https://github.com/nim-lang/Nim/blob/21ea1094ef0de2e0661835f9f8b56fa0b9eb4d17/config/nimdoc.cfg#L52-L55

it seems all that needs to be done is to use the title as the link text,
something like:

~html

title="$header_plain">$header_plain

~

as this is a stylistic choice (but probably a warranted one), I think whoever
makes the decisions would need to ok it before I move forward with a patch.
Thanks!