Execute Playbook: Documentation

Now let’s execute the playbook.

The documentation.yml file is completely non-intrusive and non-disruptive to the network. The ios_facts module will gather some information from the network. Otherwise, everything in the documentation playbook builds offline automated documentation based on the intent files.

Check for idempotency

Checking for the idempotency of the documentation is a quick and easy way to identify the changes being made to the data models or dynamic templates. If the output from the documentation playbook has changed and is not idempotent, it is possible to use this differential to provide change management or operations.It will also help identify the difference between the documentation and the running-configuration.

ansible-playbook documentation.yml –check -v 

ansible-playbook documentation.yml 

Verify output

After executing the documentation playbook, make sure to use Git to commit all the generated output into the repository.

git add *

git commit –a

git push

All the automatically and dynamically generated documentation is now part of the repository and available to be viewed. Browse to the output folders holding the configuration and Markdown files. Explore and validate them for accuracy. Using these files, it is possible to confirm exactly what will be pushed to the network in advance.

Use this methodology to include artifacts along with pull requests to merge changes into the master branch. These artifacts can be easily read and understood by others in the change management approval flow. They can also be used by network operations on a day-to-day basis without needing to log onto the network.