I'm trying to find a way to keep developer-level documentation more up-to-date with the code. One approach I'm trying is to have links between documentation and code in the same Git repo, which are navigable in both directions. I'm experimenting with both Markdown and reStructuredText, and have a couple of questions.
I've hacked up a plugin which works with the Markdown plugin to add this for Markdown links. However, Markdown links are a bit verbose for my use case because you need to provide some link text, even though I just want the link text and destination to be the same. I could just leave the link text blank but that seems ugly.
The Markdown format also allows auto-links for URLs, so in theory I could invent a custom URL scheme and write links like <code:com.foo.my.ExampleClass>. However, I can't see how I could hook into IntelliJ "go to declaration" navigation in Markdown source, as presented by that plugin. (I'm not talking about being able to click links in the HTML preview, just in the Markdown source.)
Any pointers on how I could do this?
I'm trying to find a way to record developer-oriented requirements in a way which makes them easily findable from source code in the same Git repo, with two-way navigation in IntelliJ between, say, ".java" files and ".rst" documentation source files (rather than HTML generated from reST). I raised one request (which seems to have vanished???) about my attempts to do this with Markdown but personally I would prefer to use reStructuredText because it's more suited to reference documentation. In particular, I'd like to find a way (possibly with an in-house plugin) to make the contents of certain inline intepreted text roles be treated as links to, say, Java test classes.
Unfortunately, as far as I can make out from the Psi structure view tool, and from the decompiled sources of the JetBrains Rest plugin, I can't see any way of doing this. Intepreted text sections are rendered differently, and it would be easy to navigate to the preceding Psi node to find the role, but the PsiElements for the intepreted text don't override PsiElement#getReferences (as org.intellij.plugins.markdown.lang.psi.impl.MarkdownLinkDestinationImpl does). I wondered about trying to hook into the language injection used by the Rest plugin, but it only seems to apply to text sections which are not intepreted text. I realise the Rest plugin is mainly intended for use in PyCharm, but it does enough in IntelliJ for my purposes otherwise.
Could you give me any other ideas? Or even open-source the plugin under a permissive licence so that I could fork it, or make changes and submit a pull request?
Thanks for any help you could give.