From f585889913e3ce3268ea4825d57aee5111d20672 Mon Sep 17 00:00:00 2001 From: Krishnamohan Yagneswaran <110534777+Krishnamohan33@users.noreply.github.com> Date: Fri, 3 Apr 2026 17:23:08 +0530 Subject: [PATCH 1/4] Update generate_lib.py --- tools/tensorflow_docs/api_generator/generate_lib.py | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/tools/tensorflow_docs/api_generator/generate_lib.py b/tools/tensorflow_docs/api_generator/generate_lib.py index fdeb0f6060..2537babb6d 100644 --- a/tools/tensorflow_docs/api_generator/generate_lib.py +++ b/tools/tensorflow_docs/api_generator/generate_lib.py @@ -69,7 +69,7 @@ def write_docs( extra_docs: Optional[dict[int, str]] = None, page_builder_classes: Optional[docs_for_object.PageBuilderDict] = None, ): - """Write previously extracted docs to disk. + """Write extracted API documentation to disk. This function generates markdown documentation files for each API symbol defined in the parser configuration. It also handles creation of auxiliary files such as table of contents (`_toc.yaml`), redirects (`_redirects.yaml`), and a global symbol index. Each symbol is processed into a documentation page, resolving cross-references and optionally generating search metadata and API reports. """ Write a docs page for each symbol included in the indices of parser_config to a tree of docs at `output_dir`. @@ -113,7 +113,8 @@ def write_docs( # Collect redirects for an api _redirects.yaml file. redirects = [] - + + # Optional report object used to collect API documentation metrics api_report = None if gen_report: api_report = utils.ApiReport() @@ -220,7 +221,7 @@ def extract( ] = doc_generator_visitor.DocGeneratorVisitor, filters: Optional[public_api.ApiFilter] = None, ): - """Walks the module contents, returns an index of all visited objects. + """Traverse module contents and return an index of discovered API objects. This function walks through the given Python module, applies optional filters, and collects all public API symbols using the provided visitor class. It builds and returns a structured index representing the module's API hierarchy, which is later used for documentation generation. """ The return value is an instance of `self._visitor_cls`, usually: `doc_generator_visitor.DocGeneratorVisitor` @@ -255,7 +256,7 @@ def extract( class DocGenerator: - """Main entry point for generating docs.""" + """Main entry point for generating API documentation. This class coordinates the extraction, parsing, and generation of documentation for a given Python module. It manages configuration, filters, and output structure to produce consistent API reference docs. """ def __init__( self, @@ -402,7 +403,7 @@ def make_default_filters(self) -> list[public_api.ApiFilter]: ] def run_extraction(self) -> config.ParserConfig: - """Walks the module contents, returns an index of all visited objects. + """Traverse module contents and return an index of discovered API objects. This function walks through the given Python module, applies optional filters, and collects all public API symbols using the provided visitor class. It builds and returns a structured index representing the module's API hierarchy, which is later used for documentation generation. """ Returns: An instance of `parser_config.ParserConfig`. From be193aae94de6a8490b93a26bc20b1fe7f13d3ec Mon Sep 17 00:00:00 2001 From: Krishnamohan Yagneswaran <110534777+Krishnamohan33@users.noreply.github.com> Date: Fri, 3 Apr 2026 17:24:25 +0530 Subject: [PATCH 2/4] Update generate_lib.py --- tools/tensorflow_docs/api_generator/generate_lib.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/tools/tensorflow_docs/api_generator/generate_lib.py b/tools/tensorflow_docs/api_generator/generate_lib.py index 2537babb6d..fdeb0f6060 100644 --- a/tools/tensorflow_docs/api_generator/generate_lib.py +++ b/tools/tensorflow_docs/api_generator/generate_lib.py @@ -69,7 +69,7 @@ def write_docs( extra_docs: Optional[dict[int, str]] = None, page_builder_classes: Optional[docs_for_object.PageBuilderDict] = None, ): - """Write extracted API documentation to disk. This function generates markdown documentation files for each API symbol defined in the parser configuration. It also handles creation of auxiliary files such as table of contents (`_toc.yaml`), redirects (`_redirects.yaml`), and a global symbol index. Each symbol is processed into a documentation page, resolving cross-references and optionally generating search metadata and API reports. """ + """Write previously extracted docs to disk. Write a docs page for each symbol included in the indices of parser_config to a tree of docs at `output_dir`. @@ -113,8 +113,7 @@ def write_docs( # Collect redirects for an api _redirects.yaml file. redirects = [] - - # Optional report object used to collect API documentation metrics + api_report = None if gen_report: api_report = utils.ApiReport() @@ -221,7 +220,7 @@ def extract( ] = doc_generator_visitor.DocGeneratorVisitor, filters: Optional[public_api.ApiFilter] = None, ): - """Traverse module contents and return an index of discovered API objects. This function walks through the given Python module, applies optional filters, and collects all public API symbols using the provided visitor class. It builds and returns a structured index representing the module's API hierarchy, which is later used for documentation generation. """ + """Walks the module contents, returns an index of all visited objects. The return value is an instance of `self._visitor_cls`, usually: `doc_generator_visitor.DocGeneratorVisitor` @@ -256,7 +255,7 @@ def extract( class DocGenerator: - """Main entry point for generating API documentation. This class coordinates the extraction, parsing, and generation of documentation for a given Python module. It manages configuration, filters, and output structure to produce consistent API reference docs. """ + """Main entry point for generating docs.""" def __init__( self, @@ -403,7 +402,7 @@ def make_default_filters(self) -> list[public_api.ApiFilter]: ] def run_extraction(self) -> config.ParserConfig: - """Traverse module contents and return an index of discovered API objects. This function walks through the given Python module, applies optional filters, and collects all public API symbols using the provided visitor class. It builds and returns a structured index representing the module's API hierarchy, which is later used for documentation generation. """ + """Walks the module contents, returns an index of all visited objects. Returns: An instance of `parser_config.ParserConfig`. From 6cafbbe734261a19de88138beaf5e9e7beda566d Mon Sep 17 00:00:00 2001 From: Krishnamohan Yagneswaran <110534777+Krishnamohan33@users.noreply.github.com> Date: Fri, 3 Apr 2026 17:30:49 +0530 Subject: [PATCH 3/4] Update doc_controls.py --- .../api_generator/doc_controls.py | 24 ++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/tools/tensorflow_docs/api_generator/doc_controls.py b/tools/tensorflow_docs/api_generator/doc_controls.py index ec8e0e862f..128150166f 100644 --- a/tools/tensorflow_docs/api_generator/doc_controls.py +++ b/tools/tensorflow_docs/api_generator/doc_controls.py @@ -27,6 +27,14 @@ def set_deprecated(obj: T) -> T: def is_deprecated(obj) -> bool: + """Check whether an object is marked as deprecated. + + Args: + obj: The object to check. + + Returns: + True if the object is marked as deprecated, otherwise False. + """ return hasattr(obj, _DEPRECATED) @@ -86,7 +94,14 @@ def set_custom_page_builder_cls(obj, cls): def get_custom_page_builder_cls(obj): - """Gets custom page content if available.""" + """Return the custom page builder class for an object if set. + +Args: + obj: The object to inspect. + +Returns: + The custom page builder class if available, otherwise None. +""" return getattr(obj, _CUSTOM_PAGE_BUILDER_CLS, None) @@ -345,7 +360,14 @@ def _private(self): setattr(obj, _DOC_PRIVATE, None) return obj +"""Check whether a private object should be documented. + +Args: + obj: The object to check. +Returns: + True if the object is marked for documentation, otherwise False. +""" def should_doc_private(obj) -> bool: return hasattr(obj, _DOC_PRIVATE) From 64de8a37f31aea7fbc9f7021f62f46977e48e677 Mon Sep 17 00:00:00 2001 From: Krishnamohan Yagneswaran <110534777+Krishnamohan33@users.noreply.github.com> Date: Fri, 3 Apr 2026 17:36:04 +0530 Subject: [PATCH 4/4] Update doc_controls.py --- tools/tensorflow_docs/api_generator/doc_controls.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/tools/tensorflow_docs/api_generator/doc_controls.py b/tools/tensorflow_docs/api_generator/doc_controls.py index 128150166f..9a0fea0b4b 100644 --- a/tools/tensorflow_docs/api_generator/doc_controls.py +++ b/tools/tensorflow_docs/api_generator/doc_controls.py @@ -360,7 +360,9 @@ def _private(self): setattr(obj, _DOC_PRIVATE, None) return obj -"""Check whether a private object should be documented. + +def should_doc_private(obj) -> bool: + """Check whether a private object should be documented. Args: obj: The object to check. @@ -368,7 +370,6 @@ def _private(self): Returns: True if the object is marked for documentation, otherwise False. """ -def should_doc_private(obj) -> bool: return hasattr(obj, _DOC_PRIVATE)