From 83660e031aef01f69e5b3bec21e70b58fbaf1b8b Mon Sep 17 00:00:00 2001 From: Guillaume Mulocher Date: Fri, 7 Feb 2025 14:14:18 +0100 Subject: [PATCH] doc: Enable symbol (#1016) * Doc: Enable symbols * Doc: Simplify mkdocstrings overwrite * doc: Revert some changes post meeting * Update docs/api/tests/routing.bgp.md * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> --- docs/api/tests/aaa.md | 14 +- docs/api/tests/avt.md | 25 ++-- docs/api/tests/bfd.md | 26 ++-- docs/api/tests/configuration.md | 14 +- docs/api/tests/connectivity.md | 26 ++-- docs/api/tests/cvx.md | 14 +- docs/api/tests/field_notices.md | 14 +- docs/api/tests/flow_tracking.md | 26 ++-- docs/api/tests/greent.md | 14 +- docs/api/tests/hardware.md | 14 +- docs/api/tests/interfaces.md | 26 ++-- docs/api/tests/lanz.md | 14 +- docs/api/tests/logging.md | 14 +- docs/api/tests/mlag.md | 14 +- docs/api/tests/multicast.md | 14 +- docs/api/tests/path_selection.md | 27 ++-- docs/api/tests/profiles.md | 14 +- docs/api/tests/ptp.md | 14 +- docs/api/tests/routing.bgp.md | 25 ++-- docs/api/tests/routing.generic.md | 26 ++-- docs/api/tests/routing.isis.md | 25 ++-- docs/api/tests/routing.ospf.md | 13 +- docs/api/tests/security.md | 25 ++-- docs/api/tests/services.md | 25 ++-- docs/api/tests/snmp.md | 26 ++-- docs/api/tests/software.md | 14 +- docs/api/tests/stp.md | 14 +- docs/api/tests/stun.md | 26 ++-- docs/api/tests/system.md | 26 ++-- docs/api/tests/vlan.md | 14 +- docs/api/tests/vxlan.md | 14 +- .../python/material/anta_test.html.jinja | 2 +- .../material/anta_test_input_model.html.jinja | 2 +- ...table.html => attributes_table.html.jinja} | 2 +- .../python/material/docstring.html.jinja | 36 ----- .../{examples.html => examples.html.jinja} | 0 mkdocs.yml | 134 +++++++++--------- 37 files changed, 441 insertions(+), 332 deletions(-) rename docs/templates/python/material/{attributes_table.html => attributes_table.html.jinja} (97%) delete mode 100644 docs/templates/python/material/docstring.html.jinja rename docs/templates/python/material/docstring/{examples.html => examples.html.jinja} (100%) diff --git a/docs/api/tests/aaa.md b/docs/api/tests/aaa.md index 62b3f0d62..3b4d61a87 100644 --- a/docs/api/tests/aaa.md +++ b/docs/api/tests/aaa.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for AAA tests --- + ::: anta.tests.aaa + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/avt.md b/docs/api/tests/avt.md index a44ff438a..a5d6d71ba 100644 --- a/docs/api/tests/avt.md +++ b/docs/api/tests/avt.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for Adaptive Virtual Topology (AVT) tests --- + ::: anta.tests.configuration + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/connectivity.md b/docs/api/tests/connectivity.md index ad8adfe7e..88aaa5c0b 100644 --- a/docs/api/tests/connectivity.md +++ b/docs/api/tests/connectivity.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for connectivity tests --- + ::: anta.tests.cvx + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/field_notices.md b/docs/api/tests/field_notices.md index 4a09a5cb2..745ac9ea9 100644 --- a/docs/api/tests/field_notices.md +++ b/docs/api/tests/field_notices.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for Field Notices tests --- + ::: anta.tests.field_notices + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/flow_tracking.md b/docs/api/tests/flow_tracking.md index 786f56ee7..f3a9bc476 100644 --- a/docs/api/tests/flow_tracking.md +++ b/docs/api/tests/flow_tracking.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for flow tracking tests --- + ::: anta.tests.greent + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/hardware.md b/docs/api/tests/hardware.md index cc84c0d91..f15c9f131 100644 --- a/docs/api/tests/hardware.md +++ b/docs/api/tests/hardware.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for hardware tests --- + ::: anta.tests.hardware + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/interfaces.md b/docs/api/tests/interfaces.md index e9dc1ba7a..1f6def5e0 100644 --- a/docs/api/tests/interfaces.md +++ b/docs/api/tests/interfaces.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for interfaces tests --- + ::: anta.tests.lanz + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/logging.md b/docs/api/tests/logging.md index 925fd1f73..c59d3a94d 100644 --- a/docs/api/tests/logging.md +++ b/docs/api/tests/logging.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for logging tests --- + ::: anta.tests.logging + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/mlag.md b/docs/api/tests/mlag.md index 15ab71967..d85ae1919 100644 --- a/docs/api/tests/mlag.md +++ b/docs/api/tests/mlag.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for MLAG tests --- + ::: anta.tests.mlag + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/multicast.md b/docs/api/tests/multicast.md index c89383dba..5116bd6d2 100644 --- a/docs/api/tests/multicast.md +++ b/docs/api/tests/multicast.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for multicast and IGMP tests --- + ::: anta.tests.multicast + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/path_selection.md b/docs/api/tests/path_selection.md index 68488b664..6fd956678 100644 --- a/docs/api/tests/path_selection.md +++ b/docs/api/tests/path_selection.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for Router path-selection tests --- + ::: anta.tests.profiles + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/ptp.md b/docs/api/tests/ptp.md index dbb620e77..ad0950503 100644 --- a/docs/api/tests/ptp.md +++ b/docs/api/tests/ptp.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for PTP tests --- + ::: anta.tests.ptp + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/routing.bgp.md b/docs/api/tests/routing.bgp.md index 1e0cbec8d..a3a073154 100644 --- a/docs/api/tests/routing.bgp.md +++ b/docs/api/tests/routing.bgp.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for BGP tests --- + ::: anta.tests.software + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/stp.md b/docs/api/tests/stp.md index 5692a74c6..4729c89fc 100644 --- a/docs/api/tests/stp.md +++ b/docs/api/tests/stp.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for STP tests --- + ::: anta.tests.stp + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false anta_hide_test_module_description: true - show_labels: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/stun.md b/docs/api/tests/stun.md index f4247dceb..3c5c20535 100644 --- a/docs/api/tests/stun.md +++ b/docs/api/tests/stun.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for STUN tests --- + ::: anta.tests.vlan + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false - show_labels: true anta_hide_test_module_description: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/api/tests/vxlan.md b/docs/api/tests/vxlan.md index 131e0a317..a79a0b1e3 100644 --- a/docs/api/tests/vxlan.md +++ b/docs/api/tests/vxlan.md @@ -1,6 +1,7 @@ --- anta_title: ANTA catalog for VXLAN tests --- + ::: anta.tests.vxlan + options: - show_root_heading: false - show_root_toc_entry: false - show_bases: false - merge_init_into_class: false - show_labels: true anta_hide_test_module_description: true filters: - "!test" - "!render" + merge_init_into_class: false + show_bases: false + show_labels: true + show_root_heading: false + show_root_toc_entry: false + show_symbol_type_heading: false + show_symbol_type_toc: false diff --git a/docs/templates/python/material/anta_test.html.jinja b/docs/templates/python/material/anta_test.html.jinja index a40d86a24..722c6b38e 100644 --- a/docs/templates/python/material/anta_test.html.jinja +++ b/docs/templates/python/material/anta_test.html.jinja @@ -57,7 +57,7 @@ {% set heading_level = heading_level + 1 %} {% set old_obj = obj %} {% set obj = class %} - {% include "attributes_table.html" with context %} + {% include "attributes_table.html.jinja" with context %} {% set obj = old_obj %} {% else %} {% if members_list is not none or class.is_public %} diff --git a/docs/templates/python/material/anta_test_input_model.html.jinja b/docs/templates/python/material/anta_test_input_model.html.jinja index f867ad00d..f799fd8a9 100644 --- a/docs/templates/python/material/anta_test_input_model.html.jinja +++ b/docs/templates/python/material/anta_test_input_model.html.jinja @@ -34,7 +34,7 @@ {% set heading_level = heading_level + 1 %} {% set old_obj = obj %} {% set obj = class %} - {% include "attributes_table.html" with context %} + {% include "attributes_table.html.jinja" with context %} {% set obj = old_obj %} {% endwith %} {% endif %} diff --git a/docs/templates/python/material/attributes_table.html b/docs/templates/python/material/attributes_table.html.jinja similarity index 97% rename from docs/templates/python/material/attributes_table.html rename to docs/templates/python/material/attributes_table.html.jinja index 49971459b..3ab4ba00c 100644 --- a/docs/templates/python/material/attributes_table.html +++ b/docs/templates/python/material/attributes_table.html.jinja @@ -61,7 +61,7 @@ {% set heading_level = heading_level + 1 %} {% set old_obj = obj %} {% set obj = class %} - {% include "attributes_table.html" with context %} + {% include "attributes_table.html.jinja" with context %} {% set obj = old_obj %} {% endfor %} diff --git a/docs/templates/python/material/docstring.html.jinja b/docs/templates/python/material/docstring.html.jinja deleted file mode 100644 index b12ae7e09..000000000 --- a/docs/templates/python/material/docstring.html.jinja +++ /dev/null @@ -1,36 +0,0 @@ -{% if docstring_sections %} - {{ log.debug("Rendering docstring") }} - {% for section in docstring_sections %} - {% if config.show_docstring_description and section.kind.value == "text" %} - {% if not (config.anta_hide_test_module_description and module == obj) %} - {{ section.value|convert_markdown(heading_level, html_id) }} - {% endif %} - {% elif config.show_docstring_attributes and section.kind.value == "attributes" %} - {% include "docstring/attributes.html" with context %} - {% elif config.show_docstring_functions and section.kind.value == "functions" %} - {% include "docstring/functions.html" with context %} - {% elif config.show_docstring_classes and section.kind.value == "classes" %} - {% include "docstring/classes.html" with context %} - {% elif config.show_docstring_modules and section.kind.value == "modules" %} - {% include "docstring/modules.html" with context %} - {% elif config.show_docstring_parameters and section.kind.value == "parameters" %} - {% include "docstring/parameters.html" with context %} - {% elif config.show_docstring_other_parameters and section.kind.value == "other parameters" %} - {% include "docstring/other_parameters.html" with context %} - {% elif config.show_docstring_raises and section.kind.value == "raises" %} - {% include "docstring/raises.html" with context %} - {% elif config.show_docstring_warns and section.kind.value == "warns" %} - {% include "docstring/warns.html" with context %} - {% elif config.show_docstring_yields and section.kind.value == "yields" %} - {% include "docstring/yields.html" with context %} - {% elif config.show_docstring_receives and section.kind.value == "receives" %} - {% include "docstring/receives.html" with context %} - {% elif config.show_docstring_returns and section.kind.value == "returns" %} - {% include "docstring/returns.html" with context %} - {% elif config.show_docstring_examples and section.kind.value == "examples" %} - {% include "docstring/examples.html" with context %} - {% elif config.show_docstring_description and section.kind.value == "admonition" %} - {% include "docstring/admonition.html" with context %} - {% endif %} - {% endfor %} -{% endif %} diff --git a/docs/templates/python/material/docstring/examples.html b/docs/templates/python/material/docstring/examples.html.jinja similarity index 100% rename from docs/templates/python/material/docstring/examples.html rename to docs/templates/python/material/docstring/examples.html.jinja diff --git a/mkdocs.yml b/mkdocs.yml index ed970809a..5b3c6dcb7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -98,14 +98,12 @@ plugins: inherited_members: false merge_init_into_class: true separate_signature: true - show_signature_annotations: true - signature_crossrefs: true show_root_heading: true show_root_full_path: false - # sadly symbols are for insiders only - # https://mkdocstrings.github.io/python/usage/configuration/headings/#show_symbol_type_toc - # show_symbol_type_heading: true - # show_symbol_type_toc: true + show_signature_annotations: true + show_symbol_type_heading: true + show_symbol_type_toc: true + signature_crossrefs: true # default filters here filters: ["!^_"] extensions: @@ -176,71 +174,71 @@ nav: - Installation: requirements-and-installation.md - Inventory and Test catalog: usage-inventory-catalog.md - ANTA CLI: - - Overview: cli/overview.md - - NRFU: cli/nrfu.md - - Execute commands: cli/exec.md - - Inventory from CVP: cli/inv-from-cvp.md - - Inventory from Ansible: cli/inv-from-ansible.md - - Get Inventory Information: cli/get-inventory-information.md - - Get Tests Information: cli/get-tests.md - - Check commands: cli/check.md - - Debug commands: cli/debug.md - - Tag Management: cli/tag-management.md + - Overview: cli/overview.md + - NRFU: cli/nrfu.md + - Execute commands: cli/exec.md + - Inventory from CVP: cli/inv-from-cvp.md + - Inventory from Ansible: cli/inv-from-ansible.md + - Get Inventory Information: cli/get-inventory-information.md + - Get Tests Information: cli/get-tests.md + - Check commands: cli/check.md + - Debug commands: cli/debug.md + - Tag Management: cli/tag-management.md - Advanced Usages: - - Caching in ANTA: advanced_usages/caching.md - - Developing ANTA tests: advanced_usages/custom-tests.md - - ANTA as a Python Library: advanced_usages/as-python-lib.md + - Caching in ANTA: advanced_usages/caching.md + - Developing ANTA tests: advanced_usages/custom-tests.md + - ANTA as a Python Library: advanced_usages/as-python-lib.md - Tests Documentation: - - Overview: api/tests.md - - AAA: api/tests/aaa.md - - Adaptive Virtual Topology: api/tests/avt.md - - BFD: api/tests/bfd.md - - Configuration: api/tests/configuration.md - - Connectivity: api/tests/connectivity.md - - CVX: api/tests/cvx.md - - Field Notices: api/tests/field_notices.md - - Flow Tracking: api/tests/flow_tracking.md - - GreenT: api/tests/greent.md - - Hardware: api/tests/hardware.md - - Interfaces: api/tests/interfaces.md - - LANZ: api/tests/lanz.md - - Logging: api/tests/logging.md - - MLAG: api/tests/mlag.md - - Multicast: api/tests/multicast.md - - Profiles: api/tests/profiles.md - - PTP: api/tests/ptp.md - - Router Path Selection: api/tests/path_selection.md - - Routing: - - Generic: api/tests/routing.generic.md - - BGP: api/tests/routing.bgp.md - - OSPF: api/tests/routing.ospf.md - - ISIS: api/tests/routing.isis.md - - Security: api/tests/security.md - - Services: api/tests/services.md - - SNMP: api/tests/snmp.md - - STP: api/tests/stp.md - - STUN: api/tests/stun.md - - Software: api/tests/software.md - - System: api/tests/system.md - - VXLAN: api/tests/vxlan.md - - VLAN: api/tests/vlan.md + - Overview: api/tests.md + - AAA: api/tests/aaa.md + - Adaptive Virtual Topology: api/tests/avt.md + - BFD: api/tests/bfd.md + - Configuration: api/tests/configuration.md + - Connectivity: api/tests/connectivity.md + - CVX: api/tests/cvx.md + - Field Notices: api/tests/field_notices.md + - Flow Tracking: api/tests/flow_tracking.md + - GreenT: api/tests/greent.md + - Hardware: api/tests/hardware.md + - Interfaces: api/tests/interfaces.md + - LANZ: api/tests/lanz.md + - Logging: api/tests/logging.md + - MLAG: api/tests/mlag.md + - Multicast: api/tests/multicast.md + - Profiles: api/tests/profiles.md + - PTP: api/tests/ptp.md + - Router Path Selection: api/tests/path_selection.md + - Routing: + - Generic: api/tests/routing.generic.md + - BGP: api/tests/routing.bgp.md + - OSPF: api/tests/routing.ospf.md + - ISIS: api/tests/routing.isis.md + - Security: api/tests/security.md + - Services: api/tests/services.md + - SNMP: api/tests/snmp.md + - STP: api/tests/stp.md + - STUN: api/tests/stun.md + - Software: api/tests/software.md + - System: api/tests/system.md + - VXLAN: api/tests/vxlan.md + - VLAN: api/tests/vlan.md - API Documentation: - - Class Diagram: api/class-diagram.md - - Device: api/device.md - - Inventory: api/inventory.md - - Catalog: api/catalog.md - - Commands: api/commands.md - - Tests: - - AntaTest: api/tests/anta_test.md - - Input Types: api/tests/types.md - - Tests Documentation: /api/tests/ - - Result: api/result.md - - Reporters: - - Table: api/reporter/table.md - - Markdown: api/reporter/markdown.md - - CSV: api/reporter/csv.md - - Jinja: api/reporter/jinja.md - - Runner: api/runner.md + - Class Diagram: api/class-diagram.md + - Device: api/device.md + - Inventory: api/inventory.md + - Catalog: api/catalog.md + - Commands: api/commands.md + - Tests: + - AntaTest: api/tests/anta_test.md + - Input Types: api/tests/types.md + - Tests Documentation: /api/tests/ + - Result: api/result.md + - Reporters: + - Table: api/reporter/table.md + - Markdown: api/reporter/markdown.md + - CSV: api/reporter/csv.md + - Jinja: api/reporter/jinja.md + - Runner: api/runner.md - Troubleshooting ANTA: troubleshooting.md - Contributions: contribution.md - FAQ: faq.md