OpenMgmt

• Getting Started
• Mkdocs
  • Installation
  • Mkdocs Material Theme Installation
  • Author Your Content
  • Build Content
  • Locally View Changes
• PR submission
• tooling setup
  • markdownlint-cli
  • pre-commit
    • python PIP installation
    • homebrew installation
• pre-commit setup
• Style Guidelines

This repository contains documentation and examples for using open network management tools with Arista's EOS platforms. These network management protocols include OpenConfig, NETCONF, RESTCONF and others as appropriate.

Getting Started

If you'd like to submit a contribution simply fork a copy of this repository, install mkdocs and the mkdocs material theme. Add your content (in markdown format) and open a pull request.

For the most part, it's that simple.

MkDocs

The OpenMgmt site uses the mkdocs tool to render the content into what is displayed on the web site.

Installation

Installation of mkdocs is handled via pip.

pip install mkdocs

MkDocs Material Theme Installation

Since the OpenMgmt site is using the mkdocs-material theme, you will need to install this as well.

pip install mkdocs-material

Author Your Content

The content for this site is in a collection of markdown files in the 'docs/' directory in this repository. Add your content or fixes to this directory.

Build Content

The following command will build the content so you can take a look at it on the file system. You're not likely going to need this that often. More often you're going to be interested in seeing the rendered content in your browser.

mkdocs build

Locally View Changes

mkdocs makes it easy to see the rendered content locally in your browser. It is highly recommended that you validate that your changes do not break anything in the visual rendering of the site. In order to serve the site mkdocs will start a local web server, this can be invoked via the following command from the root of your copy of the repository.

mkdocs serve

Sample mkdocs serve output

% mkdocs serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 0.68 seconds
INFO     -  [14:55:12] Serving on http://127.0.0.1:8000/openmgmt/

You can point your browser at the above URL and you'll be able to see the rendered site. Now ... assuming everything looks good, you're able generate a pull request.

PR submission

If everything looks good, submit a pull request (aka PR). A series of tests will be applied to validate the tests and a maintainer will review the PR for incorporation into the main branch. There are a few things that you can do to streamline the acceptance of your pull request. Most notable here is conformance to the style guide and aligning with the linter.

Tooling Setup

Taking some time to setup the following tooling and confirming alignment with the style guide will help to smooth the passage of your pull request.

markdownlint-cli

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-cli

Alternately, markdownlint-cli can be installed via NPM, details are available at the link above.

Pre-Commit

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.

Python PIP Installation

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-commit

Homebrew Installation

brew install pre-commit

Pre-Commit Setup

From 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.

Style Guidelines

At a high level, documentation contributions should conform to the markdown linting rules as defined in .markdownline.yaml. Details regarding formating and documentation conventions can be found in the content style guide.