Open Source Documentation

Documentation is made better when user can provide feedback and provide enhancement. pyATS strongly encourages community involvement in improving the documentation.

Here is a few examples of great enhancements to the documentation:

• Fix Typos
• Better wording, easier explanation
• More details, more examples
• Anything else to enhance the documentation

We welcome any changes to the documentation to make it easier to read, understand and provide more examples.

Available documentation

Name	Official Docs	Github repo
pyATS	https://developer.cisco.com/docs/pyats/api/	https://github.com/CiscoTestAutomation/pyats/tree/master/docs
Genie	https://developer.cisco.com/docs/genie-docs/	https://github.com/CiscoTestAutomation/genie/tree/main/docs
Unicon	https://developer.cisco.com/docs/unicon/	https://github.com/CiscoTestAutomation/unicon.plugins/tree/master/docs
Rest.connector	https://developer.cisco.com/docs/rest-connector/	https://github.com/CiscoTestAutomation/rest/tree/master/connector/docs
Yang.connector	https://developer.cisco.com/docs/yang-connector/	https://github.com/CiscoTestAutomation/yang/tree/master/connector/docs
GenieTrafficGen	https://developer.cisco.com/docs/genie-trafficgen/	https://github.com/CiscoTestAutomation/genietrafficgen/tree/master/docs
GenieWebDriver	https://developer.cisco.com/docs/genie-webdriver/	https://github.com/CiscoTestAutomation/geniewebdriver/tree/master/docs

Structure of the documentation

• The documentation is built using Sphinx
• The file format of the documentation is .rst
• The URLs of each page follows the directory structure of the pyats/docs directory on Github
• For example:
  • The file pyats/docs/cli/pyats_run.rst corresponds to the url: https://pubhub.devnetcloud.com/media/pyats/docs/cli/pyats_run.html

Contribute to documentation

To contribute, fork the repository, do the modifications and create a pull request. Once a pull request is created, it is reviewed and then merged and added to the main documentation.

Below is an example of the contribution flow.

Here we are using the pyATS docs as an example; Same steps applies to other packages

• Go to the pyATS Github repository

• On the top right corner, click Fork. (see https://help.github.com/en/articles/fork-a-repo)

• Clone the repository by running git clone https://github.com/<your_github_username>/pyats

• cd pyats/docs

• Do your modification. Now to verify everything looks as expected, do the following steps

Please make sure you have the full pyats package installed via pip install pyats[full]

• Use make install_build_deps to install all of the build dependencies

• Run make html to generate documentation in HTML

• Wait until you see Done in your terminal

• The documentation is now built and stored under the directory

pyats/docs/__build__

• Run make serve to view the documentation on your browser or navigate to the repository and open the index.html

• Create a PR after you have made your changes (see commit your changes & open a PR)

• Approved documentation changes will be reflected at the release day (Last Tuesday of the month)

How to contribute to the pyATS community

• For detail on contributing to pyATS, please follow the contribution guidelines