Documentation and examples for using open network management tools such as OpenConfig
Content is to be linted to ensure consistency of formatting. This requires using markdown-cli.
MacOS users can install markdownlint-cli via homebrew.
brew install markdownlint-cliAlternately, markdownlint-cli can be installed via NPM, details are available at the link above.
In order to automate the process of linting a pre-commit hook is utilized. This requires the installation of pre-commit. Depending on your environment, the installation process may vary.
If you're using pyenv or some other python version manager, pre-commit can be
installed via pip. This ensures that it's installed to your preferred python
environment.
pip install pre-commitbrew install pre-commitFrom the root of the repository execute pre-commit install this will add the
necessary hooks to your local git configuration and setup the necessary tooling
in order to suport development.
Install mkdocs via pip.
pip install mkdocspip install mkdocs-materialmkdocs buildIt is possible to see the locally rendered content and it is highly recommended that you validate that your changes do not break something in the visual rendering of the site. In order to locally serve the site mkdocs will start a local web server, this can be invoked via the following command.
mkdocs serveThe site should be built and generated from main. This will ensure that all of the content is integrated and
appropriately rendered. DO NOT deploy directly from a branch other than main. When there are changes to merge
generate a PR and have it merged into main. From main, issue a deployment using the mkdocs deploy function.
git pull --all # make sure you have the latest version of main
git checkout main # switch to the main branch (if necessary)
mkdocs build # render the site
mkdocs gh-deploy # deploy using the mkdocs tool