def __init__(
self,
root_title: str,
py_modules: Sequence[Tuple[str, Any]],
base_dir: Optional[Sequence[Union[str, pathlib.Path]]] = None,
code_url_prefix: Union[Optional[str], Sequence[Optional[str]]] = (),
search_hints: bool = True,
site_path: str = 'api_docs/python',
private_map: Optional[Dict[str, str]] = None,
visitor_cls: Type[doc_generator_visitor.DocGeneratorVisitor] = (
doc_generator_visitor.DocGeneratorVisitor),
api_cache: bool = True,
callbacks: Optional[List[public_api.ApiFilter]] = None,
yaml_toc: Union[bool, Type[toc_lib.TocBuilder]] = True,
gen_redirects: bool = True,
gen_report: bool = True,
extra_docs: Optional[Dict[int, str]] = None,
page_builder_classes: Optional[docs_for_object.PageBuilderDict] = None,
):
"""Creates a doc-generator.
Args:
root_title: A string. The main title for the project. Like "TensorFlow"
py_modules: The python module to document.
base_dir: String or tuple of strings. Directories that "Defined in" links
are generated relative to. **Modules outside one of these directories
are not documented**. No `base_dir` should be inside another.
code_url_prefix: String or tuple of strings. The prefix to add to "Defined
in" paths. These are zipped with `base-dir`, to set the `defined_in`
path for each file. The defined in link for `{base_dir}/path/to/file` is
set to `{code_url_prefix}/path/to/file`.
search_hints: Bool. Include metadata search hints at the top of each file.
site_path: Path prefix in the "_toc.yaml"
private_map: DEPRECATED. Use `api_generator.doc_controls`, or pass a
filter to the `callbacks` argument. A
`{"module.path.to.object": ["names"]}` dictionary. Specific
aliases that should not be shown in the resulting docs.
visitor_cls: An option to override the default visitor class
`doc_generator_visitor.DocGeneratorVisitor`.
api_cache: Bool. Generate an api_cache file. This is used to easily add
api links for backticked symbols (like `tf.add`) in other docs.
callbacks: Additional callbacks passed to `traverse`. Executed between the
`PublicApiFilter` and the accumulator (`DocGeneratorVisitor`). The
primary use case for these is to filter the list of children (see:
`public_api.ApiFilter` for the required signature)
yaml_toc: Bool which decides whether to generate _toc.yaml file or not.
gen_redirects: Bool which decides whether to generate _redirects.yaml file
or not.
gen_report: If True, a report for the library is generated by linting the
docstrings of its public API symbols.
extra_docs: To add docs for a particular object instance set it's __doc__
attribute. For some classes (list, tuple, etc) __doc__ is not writable.
Pass those docs like: `extra_docs={id(obj): "docs"}`
page_builder_classes: An optional dict of `{ObjectType:Type[PageInfo]}`
for overriding the default page builder classes.
"""
self._root_title = root_title
self._py_modules = py_modules
self._short_name = py_modules[0][0]
self._py_module = py_modules[0][1]
if base_dir is None:
# Determine the base_dir for the module
base_dir = public_api.get_module_base_dirs(self._py_module)
else:
if isinstance(base_dir, (str, pathlib.Path)):
base_dir = (base_dir, )
base_dir = tuple(pathlib.Path(d) for d in base_dir)
self._base_dir = base_dir
if not self._base_dir:
raise ValueError('`base_dir` cannot be empty')
if isinstance(code_url_prefix, str) or code_url_prefix is None:
code_url_prefix = (code_url_prefix, )
self._code_url_prefix = tuple(code_url_prefix)
if not self._code_url_prefix:
raise ValueError('`code_url_prefix` cannot be empty')
if len(self._code_url_prefix) != len(base_dir):
raise ValueError(
'The `base_dir` list should have the same number of '
'elements as the `code_url_prefix` list (they get '
'zipped together).')
self._search_hints = search_hints
self._site_path = site_path
self._private_map = private_map or {}
self._visitor_cls = visitor_cls
self.api_cache = api_cache
if callbacks is None:
callbacks = []
self._callbacks = callbacks
self._yaml_toc = yaml_toc
self._gen_redirects = gen_redirects
self._gen_report = gen_report
self._extra_docs = extra_docs
self._page_builder_classes = page_builder_classes
def __init__(
self,
root_title: str,
py_modules: Sequence[Tuple[str, Any]],
base_dir: Optional[Sequence[Union[str, pathlib.Path]]] = None,
code_url_prefix: Sequence[str] = (),
search_hints: bool = True,
site_path: str = 'api_docs/python',
private_map: Optional[Dict[str, str]] = None,
do_not_descend_map: Optional[Dict[str, str]] = None,
visitor_cls: Type[
doc_generator_visitor.DocGeneratorVisitor] = doc_generator_visitor.
DocGeneratorVisitor,
api_cache: bool = True,
callbacks: Optional[List[Callable]] = None,
yaml_toc: bool = True,
gen_redirects: bool = True,
gen_report: bool = False,
extra_docs: Optional[Dict[int, str]] = None,
):
"""Creates a doc-generator.
Args:
root_title: A string. The main title for the project. Like "TensorFlow"
py_modules: The python module to document.
base_dir: String or tuple of strings. Directories that "Defined in" links
are generated relative to. Modules outside one of these directories are
not documented. No `base_dir` should be inside another.
code_url_prefix: String or tuple of strings. The prefix to add to "Defined
in" paths. These are zipped with `base-dir`, to set the `defined_in`
path for each file. The defined in link for `{base_dir}/path/to/file` is
set to `{code_url_prefix}/path/to/file`.
search_hints: Bool. Include metadata search hints at the top of each file.
site_path: Path prefix in the "_toc.yaml"
private_map: A {"module.path.to.object": ["names"]} dictionary. Specific
aliases that should not be shown in the resulting docs.
do_not_descend_map: A {"module.path.to.object": ["names"]} dictionary.
Specific aliases that will be shown, but not expanded.
visitor_cls: An option to override the default visitor class
`doc_generator_visitor.DocGeneratorVisitor`.
api_cache: Bool. Generate an api_cache file. This is used to easily add
api links for backticked symbols (like `tf.add`) in other docs.
callbacks: Additional callbacks passed to `traverse`. Executed between the
`PublicApiFilter` and the accumulator (`DocGeneratorVisitor`). The
primary use case for these is to filter the listy of children (see:
`public_api.local_definitions_filter`)
yaml_toc: Bool which decides whether to generate _toc.yaml file or not.
gen_redirects: Bool which decides whether to generate _redirects.yaml file
or not.
gen_report: If True, a report for the library is generated by linting the
docstrings of its public API symbols.
extra_docs: Extra docs for symbols like public constants(list, tuple, etc)
that need to be added to the markdown pages created.
"""
self._root_title = root_title
self._py_modules = py_modules
self._short_name = py_modules[0][0]
self._py_module = py_modules[0][1]
if base_dir is None:
# Determine the base_dir for the module
base_dir = public_api.get_module_base_dirs(self._py_module)
else:
if isinstance(base_dir, (str, pathlib.Path)):
base_dir = (base_dir, )
base_dir = tuple(pathlib.Path(d) for d in base_dir)
self._base_dir = base_dir
if not self._base_dir:
raise ValueError('`base_dir` cannot be empty')
if isinstance(code_url_prefix, str):
code_url_prefix = (code_url_prefix, )
self._code_url_prefix = tuple(code_url_prefix)
if not self._code_url_prefix:
raise ValueError('`code_url_prefix` cannot be empty')
if len(self._code_url_prefix) != len(base_dir):
raise ValueError(
'The `base_dir` list should have the same number of '
'elements as the `code_url_prefix` list (they get '
'zipped together).')
self._search_hints = search_hints
self._site_path = site_path
self._private_map = private_map or {}
self._do_not_descend_map = do_not_descend_map or {}
self._visitor_cls = visitor_cls
self.api_cache = api_cache
if callbacks is None:
callbacks = []
self._callbacks = callbacks
self._yaml_toc = yaml_toc
self._gen_redirects = gen_redirects
self._gen_report = gen_report
self._extra_docs = extra_docs
