Dynamic Documentation and the Markdown Format

Introduction

Now that the network has been converted to code, the data models can be used to create dynamic, automated documentation.

All the intent-based variables in the data models can be manipulated to create documentation files for each network device on the network. An Ansible playbook is created to build automated documentation based on intent and data models: documentation.yml. Network documentation is automated as part of the configuration management phase.

The output includes:

• Dynamically generated intent-based configuration per device:

  • Representative of the running-configuration on the device
  • Offline version used for comparison against online running-configuration (coverage, syntax)
  • Updated as data models or logic changes

• Dynamically generated Markdown files:

  • Display data in a different format
  • Automated tabular view of custom user-written format that is dynamically updated
  • .MD file format

Markdown format

As part of the enterprise network automation, generate dynamic documentation in the Markdown format.

These templates are easy to write, as they reuse much of the template code that has already been written. These Markdown files can present full running-configurations or individual components. For example VLANs, VRFs, routes, port-channels, or physical interface configurations. These automatically generated documents scale with the network.

What is the Markdown format?

Markdown is a text-to-HTML conversion tool that allows for a friendly, easy-to-read, and easy-to-write format. Output is also very web-friendly and well-presented in browsers. By using much of the same logic, commands, and syntax, a lot of the template code exists to create these documentation templates in Jinja2.

Examples of dynamic documentation

This template generates a dynamic Markdown file displaying the variable information in tabular format. In this example, all VLANs followed by the full generated configuration of the device are displayed. Every variable in the data model is available to be manipulated into human-readable documentation files.

Below, we can see the template and what it will look like when rendered in Markdown. All variables in {{ }} will have values depending on the particular host.