No way to globally include private identifiers

[jkugler]

PyDoc is wonderful! I had it up and running in minutes, and it produced beautiful docs.

But I hit an issue. We would like to use this both for docs for our developer team, as well as producing external-facing documentation. If we want to include private identifiers in our docs, we have to update add a __pdoc__ to every file. But...if we want to produce user-facing docs, we would have to remove that.

It would be really nice if there was a command-line flag to say "include all private identifiers."

Since pdoc3 is so procedural (and not class/hierarchy based) it appears this would require quite the re-architecting of the project.

[kernc]

Listing absolute refnames only in the top-level module should work. This maybe alleviates part of your issue?

# project/__init__.py:
try:
    from _private_build import __pdoc__
except ImportError:
    pass  # Public build
...

# _private_build.py:
__pdoc__ = {} 
__pdoc__['project._private_module'] = True
__pdoc__['project._private_module2'] = True
__pdoc__['project._private_module2._something'] = True

[jkugler]

Ah, I see what is done there. Yeah, that might work. That does, however, require the developers to basically keep a catalog of all the private methods, which could get onerous in a hurry.

Thanks for the tip!

I'm reading over the Sphinx docs https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#skipping-members

(yes, I know, huge project, much more complex), but it allows you to catch an event of autodoc-skip-member(app, what, name, obj, skip, options) which you then can use to decide, at run time, whether to include or not. Something like that in pdoc3 would be neat, but I understand it would still take quite the restructuring to make happen.

[kernc]

Yeah, I guess the exceptions are explicit. __pdoc__ can be constructed in Python code, though. Something like this should work:

# _private_build.py
...
import _private_module
_private_module.__pdoc__ = {refname: True
                            for refname in something
                            if condition} 

[jkugler]

I'll have to keep that in mind.

[DjangoPeng]

Any updates here?

Same issue occurs.

[daniele-niero]

Bump attention to this