Monday, January 26 2015 @ 00:00 +0100
The promise of MGL-PAX has always been that it will be easy to generate documentation for different libraries without requiring extensive markup and relying on stable urls. For example, without PAX if a docstring in the MGL library wanted to reference the matrix class MGL-MAT:MAT from the MGL-MAT library, it would need to include ugly HTML links in the markdown:
"Returns a [some-terrible-github-link-to-html][MAT] object."
With PAX however, the uppercase symbol MAT will be automatically linked to the documentation of MAT if its whereabouts are known at documentation generation time, so the above becomes:
"Returns a MAT object."
The easiest way to tell PAX where to link is to let it generate the documentation for all libraries at the same time like this:
(document (list mgl-mat:@mat-manual mgl:@mgl-manual))
This is the gist of what MGL-PAX-WORLD does. It has a list of stuff to document, and it creates a set of HTML files. Check out how its output looks on github pages. Here is a good example of cross-links. It's easy to play with locally: just get the gh-pages branch and call UPDATE-PAX-WORLD.