Add support for implicit namespace python packages

[AWhetter]

The module finder should no longer look for __init__.py files, and the documentation should make it clear that autoapi_dirs should point directly at the top level package directory.

[oleastre]

Can we help you on this ?
What would be the preferred implementation ?

1. as described, just assume the given top level folder (or folders) are part of the package (implicit namespace).
2. add a configuration flag to either keep current behaviour or switch to the new behaviour

The first solution has the drawback to having to explicitly list all packages if you use a tree that starts with src or equivalent like;

src
├── pkg_a
└── pkg_b

[AWhetter]

Unfortunately I think we'll have to make a whole new option. It's possible that someone would want to document both a namespace package and a regular package. So mixing both in autoapi_dirs would make that difficult. The next question is do we make it work like autoapi_dirs and it will find namespaces in the folder that you give it or should you have to pass it the namespace folders directly? I think for consistency it should work like autoapi_dirs, but I like your idea of having another option to switch between behaviours because I prefer the idea of users being explicit and users passing exactly what packages they want to be documented. They can always do custom searching inside their conf.py. We can add this behavioural option do that as a separate change if it's too much in one go.

[AWhetter]

Clearly I haven't woken up yet. I just thought about your idea of a behaviour option more closely and realised that users can still do both implicit namespaces and regular packages. It just means that users will be forced into doing their own searching if they want current behaviour and to use namespace packages. But I think that makes sense.

[oleastre]

In fact my proposal is not really new, it's just the way it works for sphinx-apidoc. Switching the search behaviour to implicit namespace is just a command line flag; see http://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html#cmdoption-sphinx-apidoc-implicit-namespaces So, I could just add an autoapi_use_implicit_namespace flag (better name welcome ;) )and just add a behavior switch in the way PythonSphinxMapper interprets the given autoapi_dirs.

[AWhetter]

Sounds good. Call the option autoapi_python_use_implicit_namespaces to make it clear that it's a Python only option.

[AWhetter]

Closed via #178