When I use something like

.. automodapi:: mpdaf.tools
   :no-main-docstr:

I then get a lot of warnings about wrong references, and the generated doc does not have the links to functions/methods. Example for one function:

/home/simon/dev/mpdaf/doc/tools.rst:52: WARNING: failed to import copy_header
...
/home/simon/dev/mpdaf/doc/tools.rst:52: WARNING: toctree references unknown document u'api/copy_header'
...
/home/simon/dev/mpdaf/doc/api/mpdaf.tools.copy_header.rst:: WARNING: document isn't included in any toctree
...

It means that the generated autostuff code does not have correct references. Adding :no-main-docstr: has only one effect in the generated RST, it removes a line :

.. automodule:: {modname}

But then the generated code also has a .. currentmodule: directive, so everything should be ok. Any idea of what could be wrong here ?