How to document your own extension and linking to the official Fabric's doc online?

Daniele NieroDaniele Niero Posts: 217 ✭✭

Hi,

Suppose I have an extension where a function like this can be found (just a silly example):
function Xfo myFunction(Vec3 vec);

Suppose now that I want to generate the documentation of that extension with sphinx and following the instructions in here: http://dist.fabric-engine.com/FabricEngine/escher/Documentation/HTML/DocSystem/index.html

What I get is indeed the documentation of my extension but when it comes to the function above, although properly documented, the resulting html has not link to Xfo nor Vec3, because they weren't documented along with my extension...

This is logic but apparently Sphinx has a mechanism to be able to create cross reference between documentations. It's called intersphinx and it's a Sphinx's extension shipped with Sphinx itself.
http://www.sphinx-doc.org/en/stable/ext/intersphinx.html

So I configured my Sphinx project to look at Fabric's documentation, something along this line:

extensions = [
    'sphinx.ext.todo',
    'sphinx.ext.autodoc',
    'sphinx.ext.graphviz',
    'sphinx.ext.intersphinx',
    'FabricEngine.Sphinx.KL',
    'FabricEngine.Sphinx.DFG'
]

intersphinx_cache_limit=-1
intersphinx_mapping = {
    'fabric': ('http://docs.fabric-engine.com/FabricEngine/2.5.0/HTML', None)
}

When I build it, it clearly says loading intersphinx inventory from http://docs.fabric-engine.com/FabricEngine/2.5.0/HTML/objects.inv... (which can be also downloaded if that address is copied to your browser's navigation bar)

Unfortunately when my documentation has finished to build no cross-doc reference is really available.

My question is then: Is there anybody that tried this before and managed to make it working?

Comments

  • HelgeHelge Moderator, Fabric Employee Posts: 299 Fabric Employee

    Hey Daniele,

    sorry but this is not possible out of the box the way our documentation is setup right now. I think it's due to the fact that we only replace words with refs when they are loaded within the ASTWrapper. This is a bug really on our end. I'll file a ticket to resolve this for a future release.

    Thanks for the heads up!

    Best!

    Research Engineer @ Fabric Software

Sign In or Register to comment.