weavejester/codox — pull request #10 by davidsantiago (2012-07-15 08:54:17+00:00)
Title: Add links to source code in generated output

This pull request updates Codox so that it will include links to a given public var's source code in the generated output.

This patch works by augmenting the pipeline with an additional stage. The sequence of namespaces is generated as before from the reader. But there is an additional stage in main.clj before write is called: it calls to codox.utils/add-source-paths, which runs through the namespace sequence and updates all the publics to have an additional data item called :path, which contains a File object indicating the repo-relative file path for the source file. The output is otherwise the same, so it fits right into the creation of the "namespaces" local variable in generate-docs. I also modified the functions in writer/html.clj to include these links in a fairly obvious way.

To make this feature work, the user must add a key to the :codox project map entry called :src-dir-uri, which is prepended to the repo-root-relative file paths when the links are made. If this key is not present, no "Source" links appear in the output. If the user adds a key called :src-linenum-anchor-prefix to the :codox project entry, these Source links will link right to the line number where the function starts. This is in the hopes that users who do not wish to use github to link to the code can still make the feature work, though I am not aware of other sites you could use this with, so I imagine the most common value for this will be "L".

I'm sure you'll feel free to modify variable/configuration key names etc, as I am sure you will inevitably have to change the project version in all four places as well.