I am using org-mode to write software documentation, where API documentation of functions, variables etc. is automatically extracted from doc-strings of the code (which happens to be in Common Lisp). This documentation is then exported to HTML (I happen to do this via reStructuredText with ox-rst and Sphinx). It works largely like using Sphinx directly with Python, but with all features of org-mode, like executable code blocks.
Just to briefly show the principle, I am demonstrating the approach below somewhat simplified with Emacs Lisp. I have a code block that extracts the documentation of a function (with Common Lisp's format and using :results output raw I avoid surrounding double-quotes in the result, but for simplicity I leave them in in the brief demo below).
#+name: function-doc
#+begin_src emacs-lisp :results output raw :exports results :var name='list
(print (documentation name))
#+end_src
I then call that code block with the function I want to document, and during export this call is replaced with the resulting documentation.
#+CALL function-doc(name:'map)
The resulting documentation for map that is automatically inserted into the exported file happens to be the following.
"Map a FUNCTION across one or more SEQUENCEs, returning a sequence.
TYPE is the sequence type to return.
(fn TYPE FUNCTION SEQUENCE...)"
I can use org-mode formatting in my doc-strings, and such formatting is exported as expected.
Now comes my question. I would like to use links to API entries (e.g., the documentation of a function) within both the doc-strings of other functions, variables etc. and from within the main text (i.e., the text that is not automatically inserted). Automatically inserting targets with the name of the function is easy, I just need to extend my code block function-doc above accordingly. However, these targets are not found during the export process. Even if I have the target to the documentation of MY-FUNCTION automatically added with the code block function-doc above, when I insert the org-mode link [[MY-FUNCTION]] to that function, org-mode interrupts the export with the following error.
user-error: Unable to resolve link: "MY-FUNCTION"
Is there any way around this limitation? Is there any way that targets in the results of org-mode code blocks can be "seen" by org-mode during the export process?
I already tried various workarounds, but without success so far. For example, I tried to use org-mode macros instead of code blocks, but it is very tricky to have multi-line macro results (the tricks reported at Define org mode macro with line breaks where not sufficient for me). I was looking for a way to turn the error message about unresolved links into a warning, but all I found was the option to mark broken links as shown below. Any way to export and just ignoring (seemingly) broken links?
#+OPTIONS: broken-links:mark
I also considered to first automatically export my org file to an org with all the code block results already inserted, so that org-mode could see all the targets for the links, but obviously exporting an org file to org mode is also not possible with (seemingly) broken links.
Any help? Thanks a lot!
When using only using reStructuredText export for Sphinx, then I can use inline rST links like the following. An additional bonus here is that rST links are case insensitive, unlike org-mode links.
See also @@rst:`my-function`_@@.
If I want to export into multiple formats, then I can define an org-mode macro that generates the rST link above, as well as links for other export formats.