Navigating from Markdown & reST to code
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.
Markdown
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?
reStructuredText
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.
Please sign in to leave a comment.
I've forwarded this to my colleague responsible for RestructuredText support. Btw, sources are available in IJ Community sources under community/python/rest
Hello Hugh,
First of all, Yann is right and the sources for the reStructuredText plugin are available here. The Markdown plugin sources can be found by this link.
You're thinking in the right direction. To make it possible to navigate from RST elements to the elements in code they point to you should redefine the getReference() method of the RST element. Take a look at the References and Resolve section of the IntelliJ Platform Plugin SDK documentation. Elements like Sphinx autodoc directives can work as references. The latter may require adding new classes to the RST plugin PSI.
Now the tricky part is you want to navigate from RST elements to the elements of another language. This is indeed possible, see, for example, how you can navigate from IDEA plugin XML files to Java classes. I think, XmlAttributeValue resolution can be a good example. A similar approach can be used for RST and any other language.
I hope this will help.
Thanks, Yann and Andrey,
I had found the Markdown plugin sources but not the reST plugin, so thanks for that. It might be helpful to update the reST plugin marketplace page (https://plugins.jetbrains.com/plugin/7124-restructuredtext) because it doesn't link to the source (whereas the Markdown one does), so I assumed it was closed source.
I eventually figured out how to get a link working from Markdown to Java (just needed to crete my own trivial class overriding PsiReferenceBase<PsiElement>), so I imagine it will be very similar for reST once I can add a similar simple override of PsiElement#getReferences. I hope some day I can find the time to provide a pull request of appropriate quality, according to your contributing guidelines.
An ugly alternative for me, for organisational reasons, might be to fork the reST plugin source internally and not try to get the modifications PR'ed into the public repo. Given that the repo seems to be Apache-licensed, would that be acceptable legally?
Hi, yes, we accept PRs, please see https://plugins.jetbrains.com/docs/intellij/platform-contributions.html#contribute-code for details.