Allow importing specs from foreign doc tools #43
Description
We would like to write our SMDs in Javadoc. We already created a doclet that lets us export the information from the java sources to dim.
What is now still missing is the possibility to make sphinx aware that SMDs exist "somewhere else" and have sphinx link to these as well as generate a list of back-refs (with links) so Javadoc can also include those backrefs in it's output.
My first idea was to add a directive like this to the sphinx plugin:
.. foreign-spec:: SMD_SomeModule_SomeSpec
:link: /javadoc/path/to/class.html#MethodToJumpTo
This would tell sphinx that the SMD exists under the given path (that will be generated by a different tool).
We could then build a doclet for javadoc to generate a .rst with all the specs defined in javadoc that could then be used by sphinx to build.
Sphinx would also need to then output some kind of file containing al the back-refs for these specs as well as links to them.
That file could then again be imported in javadoc to create proper back-links.
Bonus points for also figuring out how to make
... mod::
Directive work for modules that are only described in foreign documentation tools.