tfdocs.public_api.explicit_package_contents_filter

Filter submodules, only keep what's explicitly included.

tfdocs.public_api.explicit_package_contents_filter(
    path: Sequence[str],
    parent: Any,
    children: tfdocs.public_api.Children
) -> tfdocs.public_api.Children

This filter only affects the visibility of modules. Other objects are not affected.

This filter is useful if you explicitly define your API in the packages of your library (the init.py files), but do not expliticly define that API in the __all__ variable of each module. The purpose is to make it easier to maintain that API.

This filter makes it so that modules are only documented where they are explicitly imported in an init.py

Packages

Lots of imports indirectly inject modules into package namespaces, this filter helps you ignore those. Anywhere you import pkg.sub1 it will inject sub1 into the pkg namsspace.

When filtering a package it only keeps modules that are directly impotrted in the package. This code, injects [sub0, sub1, sub2, sub3, sub4, sub_sub1, *] into the pkg namespace:

pkg/init.py

import sub0
import pkg.sub1
from pkg import sub2
from pkg.sub3 import sub_sub1
from pkg.sub4 import *

But this filter will only keep the modules [sub0, sub2, sub_sub1] in the docs for pkg.

Regular modules

For regular modules all modules in the namespace are assumed to be implementation details and/or documented in their source location. For example in this package:

pkg/
  __init__.py
  sub1.py
  sub2.py

If you import sub2 in __init__.py sub2 will documented in pkg But if you import sub2 in sub1.py sub2 will not be documented in sub1

path A tuple of names forming the path to the object.
parent The parent object.
children A list of (name, value) tuples describing the attributes of the patent.

A filtered list of children (name, value) pairs.