nimforum mirror - Everything is better with hyperlinks

gradha (orginal) [2013-05-07T00:17:39+02:00] view original

All hail the hyperlink! (and brace for tl;dr)

With this program you can take any source and (with lots of patience) filter it through idetools to generate not so pretty HTML which highlights idetools --def detection and hyperlinks Nimrod's stdlib docs if available. My reasons for developing this program were two:

Highlighting annoying idetools bugs which might be difficult to report due to the developers not having the same environment/editor (and more often than not, lazyness). Now you can filter the files and get proof that stuff doesn't work as it should. Reporting test cases is now easier.

Improving Nimrod's documentation (https://github.com/Araq/Nimrod/issues/423). On top of the module docstrings, I would like to see one day all the examples from the examples directory to be generated along the docstrings for user browsing pleasure. Of course, browsing an HTML version of a source file is crap, and here comes idetools to hyperlink all the stdlib procs in an effective way, allowing users to see an example, click a link and see the original documentation for whatever they clicked (or just hovering over it).

Not only I want the examples to be generated, I also want the embedded code snippets to be hyperlinked! For example, the webpage lists a code snippet at http://nimrod-code.org/index.html, which comes from https://github.com/Araq/Nimrod/blob/master/web/index.txt. Just like this website, the code snippet is syntax highlighted, but it would be so much sweeter to just feed it to idetools and hyperlink stdlib docs!

I understand this may not be possible for the snippets as they are, and also may not be wanted for some, so I would like to propose adding .. code-block:: idetools to the snippets. The documentation generator would see this code just before the normal nimrod code block, and say "aha, for the idetools to work, I must generate a temporary file with both the idetools part and the normal codeblock and parse that combined through idetools". So usually this idetools part would contain mainly import and maybe other variables/globals setup. Thanks to this snippet preamble the idetools hyperlinking would work. Of course, the preamble would be hidden for the end output, as it's just an internal detail for generation.

Other stuff in no particular order I wanted to mention:

The program I wrote uses brute force to feed each individual character to idetools. It is slow, and not something the nimrod doc command would need, but I wanted to stress test the idetools and found out many places were even blanks were producing idetools --def output. The nimrod doc command of course has knowledge about parsing, so a lot of time can be saved by calling idetools once per keyword, or ignoring comments/whitespace.

The HTML colors for my generation are horrible. I don't have a shrimp mantis, if somebody has, please let it give me a better CSS for the output.

There is a lot of repeated idetools output in the final HTML. It would be better if the program could put the common output/docstrings in some JS array and then use JS to generate the tooltip dynamically with the right stuff. Again, I suck at HTML and prefer to keep it that way, if somebody wants to do something like this you can give me the JS and I'll integrate it in the program (https://github.com/gradha/the_hyperlink_vs_nimrod/issues/8).

In some test cases the code block after when isMainModule: seems to get the shortest idetools stick, and rarely produces any useful idetools linkage. I'll generate some more tests cases and report them appropriately.

It's also time to update nimrod's doc generation to include the idetools signature. At the moment the hyperlink won't work for same proc names with different params. Maybe this can be avoided in the HTML generator by putting the correct info in the .idx files which are parsed to find out the HTML hrefs (https://github.com/Araq/Nimrod/issues/421).

I need to improve the program with the recent caas stuff (https://github.com/gradha/the_hyperlink_vs_nimrod/issues/2). I guess I'll leave the current version as a test case for verifying both code paths generate the same info.

Mirror of forum.nim-lang.org

150 :: Everything is better with hyperlinks