Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc: Added support for skip the TOC on fabric and device documentation #4796

Merged
merged 13 commits into from
Jan 13, 2025
Original file line number Diff line number Diff line change
@@ -1,23 +1,5 @@
# host3

## Table of Contents

- [Management](#management)
- [Management Interfaces](#management-interfaces)
- [Monitoring](#monitoring)
- [TerminAttr Daemon](#terminattr-daemon)
- [Spanning Tree](#spanning-tree)
- [Spanning Tree Summary](#spanning-tree-summary)
- [Spanning Tree Device Configuration](#spanning-tree-device-configuration)
- [Routing](#routing)
- [Router ISIS](#router-isis)
- [Router BGP](#router-bgp)
- [MPLS](#mpls)
- [MPLS and LDP](#mpls-and-ldp)
- [MPLS RSVP](#mpls-rsvp)
- [MPLS Device Configuration](#mpls-device-configuration)
- [Traffic Policies information](#traffic-policies-information)

## Management

### Management Interfaces
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
---
eos_cli_config_gen_documentation:
toc: false
Original file line number Diff line number Diff line change
@@ -1,19 +1,5 @@
# L2LS

## Table of Contents

- [Fabric Switches and Management IP](#fabric-switches-and-management-ip)
- [Fabric Switches with inband Management IP](#fabric-switches-with-inband-management-ip)
- [Fabric Topology](#fabric-topology)
- [Fabric IP Allocation](#fabric-ip-allocation)
- [Fabric Point-To-Point Links](#fabric-point-to-point-links)
- [Point-To-Point Links Node Allocation](#point-to-point-links-node-allocation)
- [Loopback Interfaces (BGP EVPN Peering)](#loopback-interfaces-bgp-evpn-peering)
- [Loopback0 Interfaces Node Allocation](#loopback0-interfaces-node-allocation)
- [ISIS CLNS interfaces](#isis-clns-interfaces)
- [VTEP Loopback VXLAN Tunnel Source Interfaces (VTEPs Only)](#vtep-loopback-vxlan-tunnel-source-interfaces-vteps-only)
- [VTEP Loopback Node allocation](#vtep-loopback-node-allocation)

## Fabric Switches and Management IP

| POD | Type | Node | Management IP | Platform | Provisioned in CloudVision | Serial Number |
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
---
root_dir: '{{ playbook_dir }}'

# Generate CSVs with fabric link info.
# Generate CSVs with fabric link info and skip TOC.
eos_designs_documentation:
topology_csv: true
p2p_links_csv: true
toc: false
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
"topology_csv": {"type": "bool", "default": False},
"p2p_links_csv_file": {"type": "str", "required": True},
"p2p_links_csv": {"type": "bool", "default": False},
"toc": {"type": "bool", "default": True},
}


Expand Down Expand Up @@ -82,6 +83,7 @@ def main(self, validated_args: dict, task_vars: dict, result: dict) -> dict:
include_connected_endpoints=validated_args["include_connected_endpoints"],
topology_csv=validated_args["topology_csv"],
p2p_links_csv=validated_args["p2p_links_csv"],
toc=validated_args["toc"],
)
if output.fabric_documentation:
result["changed"] = write_file(
Expand Down

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
validation_mode: "{{ avd_data_validation_mode }}"
generate_device_config: "{{ eos_cli_config_gen_configuration.enable | arista.avd.default(true) }}"
generate_device_doc: "{{ eos_cli_config_gen_documentation.enable | arista.avd.default(generate_device_documentation, true) }}"
device_doc_toc: true
device_doc_toc: "{{ eos_cli_config_gen_documentation.toc | arista.avd.default(true) }}"
cprofile_file: "{{ eos_cli_config_gen_cprofile_file | default(omit) }}"
delegate_to: localhost
vars:
Expand Down

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,7 @@
topology_csv: "{{ eos_designs_documentation.topology_csv | arista.avd.default(false) }}"
p2p_links_csv_file: "{{ fabric_dir }}/{{ fabric_name }}-p2p-links.csv"
p2p_links_csv: "{{ eos_designs_documentation.p2p_links_csv | arista.avd.default(false) }}"
toc: "{{ eos_designs_documentation.toc | arista.avd.default(true) }}"
mode: "0o664"
delegate_to: localhost
check_mode: false
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,13 @@
{# context used to hide password and keys #}
{% set hide_passwords = eos_cli_config_gen_documentation.hide_passwords | arista.avd.default(true) %}
# {{ hostname | arista.avd.default(inventory_hostname) }}
{% if eos_cli_config_gen_documentation.toc is not arista.avd.defined(false) %}

## Table of Contents

<!-- toc -->
<!-- toc -->
{% endif %}
gmuloc marked this conversation as resolved.
Show resolved Hide resolved
{# Management #}
{% include 'documentation/management.j2' %}
{# CVX #}
Expand Down
15 changes: 14 additions & 1 deletion python-avd/pyavd/_eos_cli_config_gen/schema/__init__.py

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Original file line number Diff line number Diff line change
Expand Up @@ -20,3 +20,7 @@ keys:
description: |
Replace the input data using the `hide_passwords` filter in the Jinja2 templates by '<removed>' in the documentation if true.
default: true
toc:
type: bool
default: true
description: Generate the table of content(TOC) on device documentation.
Original file line number Diff line number Diff line change
Expand Up @@ -30,17 +30,23 @@ class FabricDocumentationFacts(AvdFacts):
_hostvars = NotImplemented
shared_utils = NotImplemented

def __init__(self, avd_facts: dict[str, dict], structured_configs: dict[str, dict], fabric_name: str, include_connected_endpoints: bool) -> None: # pylint: disable=super-init-not-called
def __init__(self, avd_facts: dict[str, dict], structured_configs: dict[str, dict], fabric_name: str, include_connected_endpoints: bool, toc: bool) -> None: # pylint: disable=super-init-not-called
self.avd_switch_facts = {hostname: facts["switch"] for hostname, facts in get(avd_facts, "avd_switch_facts", required=True).items()}
self._fabric_name = fabric_name
self.structured_configs = structured_configs
self._include_connected_endpoints = include_connected_endpoints
self._toc = toc

@cached_property
def fabric_name(self) -> str:
"""Fabric Name used for heading of Markdown doc."""
return self._fabric_name

@cached_property
def toc(self) -> bool:
"""Generate the table of content(TOC) on device documentation."""
MaheshGSLAB marked this conversation as resolved.
Show resolved Hide resolved
return self._toc

@cached_property
def fabric_switches(self) -> list[dict]:
"""List of fabric switches."""
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,13 @@
that can be found in the LICENSE file.
#}
# {{ fabric_name }}
{% if toc is not arista.avd.defined(false) %}

## Table of Contents

<!-- toc -->
<!-- toc -->
{% endif %}

## Fabric Switches and Management IP

Expand Down
9 changes: 9 additions & 0 deletions python-avd/pyavd/_eos_designs/schema/__init__.py

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions python-avd/pyavd/_eos_designs/schema/eos_designs.schema.yml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Original file line number Diff line number Diff line change
Expand Up @@ -31,3 +31,7 @@ keys:
description: Generate P2P links CSV with all routed point-to-point links between devices.
type: bool
default: false
toc:
type: bool
default: true
description: Generate the table of content(TOC) on fabric documentation.
2 changes: 2 additions & 0 deletions python-avd/pyavd/api/fabric_documentation/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@ class FabricDocumentation:
fabric_documentation: Fabric Documentation as Markdown.
topology_csv: Topology CSV containing the physical interface connections for every device.
p2p_links_csv: P2P links CSV containing the Routed point-to-point links.
toc: Generate the table of content(TOC) on fabric documentation.
"""

fabric_documentation: str = ""
topology_csv: str = ""
p2p_links_csv: str = ""
toc: str = ""
ClausHolbechArista marked this conversation as resolved.
Show resolved Hide resolved
8 changes: 5 additions & 3 deletions python-avd/pyavd/get_fabric_documentation.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ def get_fabric_documentation(
include_connected_endpoints: bool = False,
topology_csv: bool = False,
p2p_links_csv: bool = False,
toc: bool = True,
) -> FabricDocumentation:
"""
Build and return the AVD fabric documentation.
Expand All @@ -36,6 +37,7 @@ def get_fabric_documentation(
include_connected_endpoints: Includes connected endpoints in the fabric documentation when set to True.
topology_csv: Returns topology CSV when set to True.
p2p_links_csv: Returns P2P links CSV when set to True.
toc: Skip TOC when set to False.

Returns:
FabricDocumentation object containing the requested documentation areas.
Expand All @@ -48,16 +50,16 @@ def get_fabric_documentation(
from .templater import Templar
# pylint: enable=import-outside-toplevel

fabric_documentation_facts = FabricDocumentationFacts(avd_facts, structured_configs, fabric_name, include_connected_endpoints)
fabric_documentation_facts = FabricDocumentationFacts(avd_facts, structured_configs, fabric_name, include_connected_endpoints, toc)
result = FabricDocumentation()
doc_templar = Templar(precompiled_templates_path=EOS_DESIGNS_JINJA2_PRECOMPILED_TEMPLATE_PATH)
if fabric_documentation:
fabric_documentation_facts_dict = fabric_documentation_facts.render()
result.fabric_documentation = doc_templar.render_template_from_file("fabric_documentation.j2", fabric_documentation_facts_dict)
if include_connected_endpoints:
result.fabric_documentation += "\n" + doc_templar.render_template_from_file("connected_endpoints_documentation.j2", fabric_documentation_facts_dict)

result.fabric_documentation = add_md_toc(result.fabric_documentation, skip_lines=3)
if toc:
result.fabric_documentation = add_md_toc(result.fabric_documentation, skip_lines=3)

if topology_csv:
result.topology_csv = _get_topology_csv(fabric_documentation_facts)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,8 @@ def test_get_device_doc(molecule_host: MoleculeHost) -> None:
validate_structured_config(structured_config)

expected_doc = molecule_host.doc

device_doc = get_device_doc(structured_config, add_md_toc=True)
add_md_toc = get(structured_config, "eos_cli_config_gen_documentation.toc", default=True)
device_doc = get_device_doc(structured_config, add_md_toc=add_md_toc)

assert isinstance(device_doc, str)
assert device_doc == expected_doc
Loading