I'm currently writing my Python module's documentation, using Sphinx.
While documenting some functions, if found myself writing things like:
"""
Some documentation.
:param foo: My param.
:raises my_module.some.wicked.but.necessary.hierarchy.MyException: Something bad happenned.
"""
This works fine, and Sphinx even links my_module.some.wicked.but.necessary.hierarchy.MyException to the documentation of my exception class.
However, I can see two issues here:
- Having to type the complete module path to the exception is tedious. Not a big deal but I can understand how this avoids ambiguity when actually parsing the documentation. So I might live with that.
- The generated documentation also lists the complete name (including the module path).
This second point makes the output rather hard to read and not nice at all. It clutters the documentation and doesn't bring much since one can click the link to get a complete definition of the exception class anyway.
I tried to write it as a relative path (using ..hierarchy.MyException for instance, but Sphinx would not find the class and the link would be broken).
Is there a way to define a default alias/caption that will be used instead of the complete path, whenever I reference my exception class ? I'd obviously like that the link remains as it is: I just want a nicer (shorter) caption.
If not, is there an option somewhere in Sphinx that tells it to avoid displaying the complete module path for some objects ? An option of some sort ?
