Add source links to macros.lissp

sphinx.ext.viewcode makes it fairly easy to add links to a source page in the API docs, at least if the source is Python. Linking to the compiled Hissp seems less useful, although I haven't even gotten that much working.

I'd need to add a Sphinx extension to do this. (The conf.py can also be a Sphinx extension given a setup() function.) I've already got a lissp_lexer and lissp_directive. I'd need something like app.events.connect("viewcode-find-source", ... to handle the appropriate event. Experiments prove this can work with non-Python files, although I'm not sure if I can add syntax highlighting.

Linking to the appropriate position in the macros.lissp source file requires writing a program for tracking the line numbers of definitions. Just compiling the file executes it, so I might as well use the compile time namespace to determine when a top-level definition has happened, rather than try to figure it out statically.

The machinery already partially exists to do this. The Lexer and Lissp classes have some position tracking for error messages. I've resisted putting that in the compiler, which might be compiling Hissp that hasn't even been read from text. It's not supposed to have to know anything about the reader. I've certainly thought about source mapping for debuggers though. Tuples can't carry metadata, and I don't want to use anything more complicated instead. Not even a tuple subclass. That would violate core design goals of Hissp.

However, when examining this problem I realized that metadata could be transmitted from the reader to the compiler out-of-band, at least at the granularity of top-level forms, either through a parameter if the reader is driving, or through a callback. This would take more reworking than I'd like to tackle before the next release, but seems doable.

The metadata could then be emitted as a comment (similar to macroexpansions) or added to __annotations__ or something like that.

gilch / hissp

Add source links to macros.lissp #231