Module documentation pages are empty about bruges HOT 4 CLOSED

I have semi-fixed this in develop http://bruges.readthedocs.io/en/develop/ — so it will be fixed in the next point release.

The problem is that sphinx seems to only accept the implicit module paths, e.g. bruges.reflection.reflection.shuey(). I think this is ugly and confusing. The __init__.py files provide the preferred API, e.g. bruges.reflection.shuey(). But I can't figure out how to get sphinx to use those. Advice welcome!

I guess there are a few ways to deal with this:

• Stop trying to impose an API and just use the implicit paths (but some of them are long and ugly).
• Get rid of the subpackages (i.e. folder in bruges/bruges) and just put all the subpaths into submodules... but this would make some of those files quite long.
• Get rid of the whole concept of subpackages/submodules and just make bruges completely flat (more like numpy).

I guess I could take a closer look at how scipy or sklearn are organized, since that's basically the kind of namespace / structure we were going for.

from bruges.

@kwinkunks the flat API of numpy is all done in the __init__.py. It's better and avoids breaking things when you move stuff around inside the project. I regreted not doing this from the start in Fatiando.

But it should work. I have it working for GMT/Python. I'll take a look and see if I can get it to work. You develop against a develop branch instead of master, right?

from bruges.

Would you be interested in building the docs and deploying to Github pages from Travis? I can set this up if you want. A bit more work but you have total control over the deploy.

from bruges.

OK, I got it working. It was a change in sphinx. They removed documenting imported members by default: sphinx-doc/sphinx#3235 I had come across this before but completely forgot. The problem is that you have to build the docs in two steps. First run sphinx-autogen and then sphinx-build. autogen as an --imported-members option to generate the correct pages. I included this in the Makefile.

I don't know how this works in Read The Docs but it should work. There must be a way to customize the rtd build.

from bruges.