add platforms page

docs/pages/_meta.json

@@ -5,6 +5,7 @@
   },
   "installation": "Installation",
   "configuration": "Configuration",
+  "platforms": "Platforms",
   "plugins": "Plugins",
   "documentation": {
     "title": "Documentation",

docs/pages/installation.mdx

@@ -18,7 +18,7 @@ You should be able to proceed with the automatic installation:
 curl https://install.hyperglass.dev | sudo bash
 ```
 
-<Callout type="warning" title="Piping to bash">
+<Callout type="warning">
   **Piping to bash**
   <br /> You should be _very_ worried when someone asks you to do what I just did. Downloading a bash
   script from the internet and piping it to `bash` with root privileges is a terrible idea, unless you

docs/pages/platforms.mdx

@@ -0,0 +1,63 @@
+---
+description: Platforms supported by hyperglass
+---
+
+import { Code, Table, Td, Th, Tr } from 'nextra/components';
+import { Callout } from 'nextra-theme-docs';
+import platforms from '~/platforms.json';
+
+export const NotSupported = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="#edae49" viewBox="0 0 16 16">
+    <path d="M8 15A7 7 0 1 1 8 1a7 7 0 0 1 0 14zm0 1A8 8 0 1 0 8 0a8 8 0 0 0 0 16z" />
+    <path d="M4.646 4.646a.5.5 0 0 1 .708 0L8 7.293l2.646-2.647a.5.5 0 0 1 .708.708L8.707 8l2.647 2.646a.5.5 0 0 1-.708.708L8 8.707l-2.646 2.647a.5.5 0 0 1-.708-.708L7.293 8 4.646 5.354a.5.5 0 0 1 0-.708z" />
+  </svg>
+);
+
+export const Supported = () => (
+  <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="#35b246" viewBox="0 0 16 16">
+    <path d="M16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0zm-3.97-3.03a.75.75 0 0 0-1.08.022L7.477 9.417 5.384 7.323a.75.75 0 0 0-1.06 1.06L6.97 11.03a.75.75 0 0 0 1.079-.02l3.992-4.99a.75.75 0 0 0-.01-1.05z" />
+  </svg>
+);
+
+export const Platforms = () => (
+  <Table>
+    <tbody>
+      <Tr>
+        <Th>Platform Keys</Th>
+        <Th>Natively Supported</Th>
+      </Tr>
+      {platforms.map(([platform, native]) => (
+        <Tr key={platform}>
+          <Td>
+            <Code>{platform}</Code>
+          </Td>
+          <Td align="center">{native ? <Supported /> : <NotSupported />}</Td>
+        </Tr>
+      ))}
+    </tbody>
+  </Table>
+);
+
+hyperglass uses [Netmiko](https://github.com/ktbyers/netmiko) to interact with devices via SSH/telnet. [All platforms supported by Netmiko](https://github.com/ktbyers/netmiko/blob/develop/PLATFORMS.md) are supported by hyperglass.
+
+## Netmiko Platforms
+
+<Callout type="info">
+  Just because Netmiko supports a given platform doesn't mean it will automatically work with
+  hyperglass. hyperglass has a limited number of built in directives (listed below). Any platforms
+  other than the ones listed below will require you to [add a custom
+  directive](/configuration/examples/add-your-own-command) for each command you wish to make
+  available.
+</Callout>
+
+<br />
+
+<Platforms />
+
+## Other Platforms
+
+| Platform          | Key    |                             Natively Supported                              |
+| :---------------- | :----- | :-------------------------------------------------------------------------: |
+| FRRouting         | `frr`  |                                <Supported/>                                 |
+| BIRD              | `bird` |                                <Supported/>                                 |
+| Any HTTP Endpoint | `http` | [See HTTP Device Docs](/configuration/reference/devices#http-configuration) |

hyperglass/util/docs.py

@@ -0,0 +1,27 @@
+"""Helpers for hyperglass docs."""
+
+# Standard Library
+import json
+from pathlib import Path
+
+
+def create_platform_list() -> str:
+    """Create a list of platforms as a typescript file for use by the docs."""
+    # Third Party
+    from netmiko.ssh_dispatcher import CLASS_MAPPER  # type: ignore
+
+    project_root = Path(__file__).parent.parent.parent
+
+    dir_ = project_root / "docs"
+    file_ = dir_ / "platforms.json"
+
+    builtin_directives = project_root / "hyperglass" / "defaults" / "directives"
+
+    names = [f.stem for f in builtin_directives.iterdir() if not f.name.startswith("_")]
+
+    platforms = [[p, p in names] for p in CLASS_MAPPER.keys()]
+
+    with file_.open("w+") as opened_file:
+        json.dump(platforms, opened_file)
+
+    return f"Wrote platforms to {file_!s}"

pyproject.toml

@@ -61,11 +61,11 @@ isort = "^5.10.1"
 pep8-naming = "^0.13.2"
 pre-commit = "^2.20.0"
 pytest = "^7.2.0"
+pytest-asyncio = "^0.20.3"
 pytest-dependency = "^0.5.1"
 ruff = "v0.0.194"
 stackprinter = "^0.2.10"
 taskipy = "^1.10.3"
-pytest-asyncio = "^0.20.3"
 
 [tool.black]
 line-length = 100
@@ -95,6 +95,7 @@ reportMissingTypeStubs = true
 
 [tool.taskipy.tasks]
 check = {cmd = "task lint && task ui-lint", help = "Run all lint checks"}
+docs-platforms = {cmd = "python3 -c 'from hyperglass.util.docs import create_platform_list;print(create_platform_list())'"}
 format = {cmd = "black hyperglass", help = "Run Black"}
 lint = {cmd = "ruff hyperglass", help = "Run Ruff Linter"}
 sort = {cmd = "isort hyperglass", help = "Run iSort"}