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