--all-submodules flag still respects __all__

[Railslide]

Running pdoc with the --all-submodules flag doesn't seem to have any effect on the generated documentation.

Example: running pdoc --html mymodule.py --all-submodules against the following code

class MyPublicClass(object):
    """docstring for MyPublicClass"""
    def __init__(self, arg):
        self.arg = arg


class PrivateClass(object):
    """docstring for PrivateClass"""
    def __init__(self, arg):
        self.arg = arg


__all__ = ['MyPublicClass']

results in only MyPublicClass being included in the docs.

[Railslide]

OK, I figured out that (as the name suggest) --all-submodules works just with submodules. Any plan of integrating the same behaviour also on a module level?

On a side note, it could be probably helpful to specify that packages needs to be installed before generating documentation. It probably goes without saying in most of the occasions, but knowing it in advance would have saved me a bit of time when testing the --all-submodules flag :)

[BurntSushi]

As you mentioned, the --all-submodules flag shouldn't have any affect on the output of your code.

Any plan of integrating the same behaviour also on a module level?

I'm not sure I follow. pdoc is a tool for documenting the public interface of a module. You've declared your public interface using __all__, so that is what pdoc uses. If you remove __all__, then both MyPublicClass and PrivateClass will be included.

On a side note, it could be probably helpful to specify that packages needs to be installed before generating documentation.

Do you want to submit a PR for this? I'm not sure I understand your concerns (how can you generate documentation for something that you don't have?), so it would probably be best if your worded it. :-)

[Railslide]

I'm not sure I follow. pdoc is a tool for documenting the public interface of a module. You've declared your public interface using __all__, so that is what pdoc uses. If you remove __all__, then both MyPublicClass and PrivateClass will be included.

I agree that it goes over the current goal of pdoc. The reason why I was asking it is because I was looking for a way for generating internal documentation (i.e. the one to be used by the members of the team, where it would make sense to document everything). I solved by manually removing __all__ before generating documentation, but it is a quite error prone approach and I was hoping for a better way to achieve the same thing.

Do you want to submit a PR for this? I'm not sure I understand your concerns (how can you generate documentation for something that you don't have?), so it would probably be best if your worded it. :-)

I'll open a new issue for this, perhaps with a better explanation and some examples :)

[BurntSushi]

I understand the use case, but I'm skeptical of adding more options/exceptions than there already are.

You could do something like this:

if os.getenv('DEV_INTERNAL') is None:
    __all__ = ['my', 'public', 'interface']

And use DEV_INTERNAL=1 pdoc module to generate internal docs.

[pzelnip]

The downside to that is that you're then modifying/cluttering the code, and you'd have to remember to do it on every module. Ideally it'd be nice to be able to have pdoc itself handle this (ie - rather than putting an env var check in client code, have a switch for pdoc where if given, it ignores the __all__ attribute).