mirror/checktheroads-hyperglass
1
0
Fork 0
mirror of https://github.com/checktheroads/hyperglass synced 2024-05-11 05:55:08 +00:00
Code Releases Activity

update docs

Browse Source
This commit is contained in:
checktheroads
2020-04-21 03:30:05 -07:00
parent f443afa138
commit 6a80ac2098
14 changed files with 279 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/docs/api.mdx
View File

@@ -56,7 +56,7 @@ FastAPI provides built in support for both [Swagger UI](https://swagger.io/tools
## Example
```yaml
```yaml title="hyperglass.yaml"
docs:
base_url: https://lg.example.net
description: ""

2
docs/docs/cache.mdx
View File

@@ -24,7 +24,7 @@ hyperglass caches every query response to a Redis database, and always responds
## Example
```yaml
```yaml title="hyperglass.yaml"
cache:
database: 0
host: localhost

2
docs/docs/commands.mdx
View File

@@ -44,7 +44,7 @@ Only the command you specify will be overridden.
Each command definition carries the following structure:
```yaml
```yaml title="commands.yaml"
command_name:
ipv4_default: ...
bgp_route: ...

4
docs/docs/configuration.mdx
View File

@@ -61,7 +61,7 @@ The `netmiko_delay_factor` parameter should only be used if you're experiencing
#### Example
```yaml
```yaml title="hyperglass.yaml"
debug: false
developer_mode: false
org_name: Beloved Hyperglass User
@@ -92,7 +92,7 @@ From the top level, the following subsections may be defined and configured:
To add, as an example, a Cisco router, add the following to your `devices.yaml`, with the relevant details changed for your device:
```yaml
```yaml title="devices.yaml"
routers:
- name: router01.pop01
address: 10.0.0.1

18
docs/docs/devices.mdx
View File

@@ -17,21 +17,21 @@ import Code from "../src/components/JSXCode";
## All Device Parameters
| Parameter | Type | Description |
| :------------------ | :-----: | :-------------------------------------------------------------------------------------------------------------------------------- |
| :------------------ | :-----: | :----------------------------------------------------------------------------------------------------------------- |
| <R/> `name` | String | Device hostname. This is not user-facing. |
| <R/> `address` | String | Device management hostname or IP address. |
| <R/> `network` | String | Primary network this device is a member of. Used for device grouping. Usually something like 'AS65000'. |
| <R/> `display_name` | String | Device's user-facing name. |
| <R/> `port` | Integer | TCP port used to connect to the device. |
| <R/> `nos` | String | Network Operating System. <MiniNote>Must be a <Link to="/docs/platforms">supported platform</Link>.</MiniNote> |
| <R/>`credential` | | <Link to="#credential">Device Credential Configuration</Link> |
| <R/>`vrfs` | | <Link to="#vrf">Device VRF Configuration</Link> |
| `proxy` | | <Link to="#proxy">SSH Proxy Configuration</Link> |
| `ssl` | | <Link to="#ssl">SSL Configuration</Link> for devices using [hyperglass-agent](https://github.com/checktheroads/hyperglass-agent). |
| <R/>`credential` | | [Device Credential Configuration](#credential) |
| <R/>`vrfs` | | [Device VRF Configuration](#vrf) |
| `proxy` | | [SSH Proxy Configuration](#proxy) |
| `ssl` | | [SSL Configuration](#ss;) for devices using [hyperglass-agent](https://github.com/checktheroads/hyperglass-agent). |
### `proxy`
Any device that uses SSH (see <Link to="/docs/platforms">platforms</Link> for breakdown) can be accessed through an intermediary SSH "proxy". The process is nearly identical to using local SSH tunneling, e.g. `ssh -L local_port:remote_device:remote_port username@proxy_server -p proxy_port`.
Any device that uses SSH (see [platforms](platforms.mdx) for breakdown) can be accessed through an intermediary SSH "proxy". The process is nearly identical to using local SSH tunneling, e.g. `ssh -L local_port:remote_device:remote_port username@proxy_server -p proxy_port`.
| Parameter | Type | Default | Description |
| :---------------- | :-----: | :------------ | :--------------------------------------------------------------------------------------------------------------------- |
@@ -128,7 +128,7 @@ Each VRF may enable, disable, or customize the contextual help menu for each ena
For example:
```yaml
```yaml title="devices.yaml"
info:
bgp_route:
enable: true
@@ -151,7 +151,7 @@ Telnet support is provided via the underlying device connection handling framewo
For example:
```yaml {3-4}
```yaml {3-4} title="devices.yaml"
routers:
- name: router01
nos: cisco_ios_telnet
@@ -163,7 +163,7 @@ routers:
Below is a full example with nearly every available knob turned:
```yaml
```yaml title="devices.yaml"
routers:
# HTTP/hyperglass-agent device
- name: router01

2
docs/docs/logging.mdx
View File

@@ -105,7 +105,7 @@ If the `provider` field is set to `'generic'`, the webhook will POST JSON data i
## Full example
```yaml
```yaml title="hyperglass.yaml"
logging:
directory: /var/log
format: json

2
docs/docs/messages.mdx
View File

@@ -32,7 +32,7 @@ All user-facing status messages can be customized if needed.
## Example
```yaml
```yaml title="hyperglass.yaml"
messages:
acl_denied: "{target} is a member of {denied_network}, which is not allowed."
acl_not_allowed: "{target} is not allowed."

4
docs/docs/production.mdx
View File

@@ -13,7 +13,7 @@ You'll want to run hyperglass behind a reverse proxy in production to serve the
The following file can be placed anywhere, and referenced at runtime with `sudo caddy run -config <file name>`. The highlighted lines should be replaced with your installation's specific variables.
```text {1,2,4,5,8,11}
```text {1,2,4,5,8,11} title="Caddy"
lg.example.com:443 {
tls person@example.com
file_server {
@@ -38,7 +38,7 @@ The `tls` directive will tell Caddy to automatically use Let's Encrypt to genera
The following file can be placed at `/etc/nginx/sites-enabled/hyperglass`. It supports IPv6, and will automatically redirect to HTTPS. The highlighted lines should be replaced with your installation's specific variables.
```nginx {4,9,10,17,19}
```nginx {4,9,10,17,19} title="NGINX"
server {
listen 80;
listen [::]:80;

12
docs/docs/queries.mdx
View File

@@ -24,7 +24,7 @@ Each query type may be disabled, enabled, or customized. The `display_name` para
#### Example
<!-- prettier-ignore -->
```yaml
```yaml title="hyperglass.yaml"
queries:
bgp_route:
display_name: BGP Route
@@ -53,7 +53,7 @@ If using `select` mode, you may define a list of communities the users can choos
#### Example
```yaml
```yaml title="hyperglass.yaml"
queries:
bgp_community:
enable: true
@@ -80,7 +80,7 @@ If using `input` mode, hyperglass allows you to override the default regular exp
#### Example
<!-- prettier-ignore -->
```yaml
```yaml title="hyperglass.yaml"
queries:
bgp_community:
enable: true
@@ -106,7 +106,7 @@ Regular expression patterns must be enclosed in single quotes, e.g. `'^.*$'`
#### Example
<!-- prettier-ignore -->
```yaml
```yaml title="hyperglass.yaml"
queries:
bgp_aspath:
display_name: BGP AS Path
@@ -137,7 +137,7 @@ AS Path regular expression patterns may also be customized, should you wish to m
#### Example
<!-- prettier-ignore -->
```yaml
```yaml title="hyperglass.yaml"
queries:
ping:
display_name: Ping
@@ -154,7 +154,7 @@ queries:
#### Example
<!-- prettier-ignore -->
```yaml
```yaml title="hyperglass.yaml"
queries:
traceroute:
display_name: Traceroute

2
docs/docs/ui.mdx
View File

@@ -169,7 +169,7 @@ Currently, only [Google Fonts](https://fonts.google.com/) are supported.
## Example
```yaml
```yaml title="hyperglass.yaml"
web:
credit:
enable: true

6
docs/package.json
View File

@@ -9,9 +9,9 @@
"deploy": "docusaurus deploy"
},
"dependencies": {
"@docusaurus/core": "^2.0.0-alpha.43",
"@docusaurus/plugin-sitemap": "^2.0.0-alpha.37",
"@docusaurus/preset-classic": "^2.0.0-alpha.43",
"@docusaurus/core": "^2.0.0-alpha.50",
"@docusaurus/plugin-sitemap": "^2.0.0-alpha.50",
"@docusaurus/preset-classic": "^2.0.0-alpha.50",
"classnames": "^2.2.6",
"prismjs": "^1.19.0",
"prop-types": "^15.7.2",

206
docs/src/theme/CodeBlock/index.js Executable file → Normal file
View File

@@ -1,10 +1,12 @@
/**
* Copyright (c) 2017-present, Facebook, Inc.
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
/* eslint-disable jsx-a11y/no-noninteractive-tabindex */
import React, { useEffect, useState, useRef } from "react";
import classnames from "classnames";
import Highlight, { defaultProps } from "prism-react-renderer";
@@ -13,9 +15,79 @@ import defaultTheme from "./dracula";
import Clipboard from "clipboard";
import rangeParser from "parse-numeric-range";
import useDocusaurusContext from "@docusaurus/useDocusaurusContext";
import useThemeContext from "@theme/hooks/useThemeContext";
import styles from "./styles.module.css";
const highlightLinesRangeRegex = /{([\d,-]+)}/;
const getHighlightDirectiveRegex = (
languages = ["js", "jsBlock", "jsx", "python", "html"]
) => {
// supported types of comments
const comments = {
js: {
start: "\\/\\/",
end: "",
},
jsBlock: {
start: "\\/\\*",
end: "\\*\\/",
},
jsx: {
start: "\\{\\s*\\/\\*",
end: "\\*\\/\\s*\\}",
},
python: {
start: "#",
end: "",
},
html: {
start: "<!--",
end: "-->",
},
};
// supported directives
const directives = [
"highlight-next-line",
"highlight-start",
"highlight-end",
].join("|");
// to be more reliable, the opening and closing comment must match
const commentPattern = languages
.map(
(lang) =>
`(?:${comments[lang].start}\\s*(${directives})\\s*${comments[lang].end})`
)
.join("|");
// white space is allowed, but otherwise it should be on it's own line
return new RegExp(`^\\s*(?:${commentPattern})\\s*$`);
};
// select comment styles based on language
const highlightDirectiveRegex = (lang) => {
switch (lang) {
case "js":
case "javascript":
case "ts":
case "typescript":
return getHighlightDirectiveRegex(["js", "jsBlock"]);
case "jsx":
case "tsx":
return getHighlightDirectiveRegex(["js", "jsBlock", "jsx"]);
case "html":
return getHighlightDirectiveRegex(["js", "jsBlock", "html"]);
case "python":
case "py":
return getHighlightDirectiveRegex(["python"]);
default:
// all comment types
return getHighlightDirectiveRegex();
}
};
const codeBlockTitleRegex = /title=".*"/;
export default ({ children, className: languageClassName, metastring }) => {
(typeof global !== "undefined" ? global : window).Prism = Prism;
@@ -26,10 +98,29 @@ export default ({ children, className: languageClassName, metastring }) => {
themeConfig: { prism = {} },
},
} = useDocusaurusContext();
// const [showCopied, setShowCopied] = useState(false);
const [showCopied, setShowCopied] = useState(false);
const [mounted, setMounted] = useState(false);
// The Prism theme on SSR is always the default theme but the site theme
// can be in a different mode. React hydration doesn't update DOM styles
// that come from SSR. Hence force a re-render after mounting to apply the
// current relevant styles. There will be a flash seen of the original
// styles seen using this current approach but that's probably ok. Fixing
// the flash will require changing the theming approach and is not worth it
// at this point.
useEffect(() => {
setMounted(true);
}, []);
const target = useRef(null);
const button = useRef(null);
let highlightLines = [];
let codeBlockTitle = "";
const { isDarkTheme } = useThemeContext();
const lightModeTheme = prism.theme || defaultTheme;
const darkModeTheme = prism.darkTheme || lightModeTheme;
const prismTheme = isDarkTheme ? darkModeTheme : lightModeTheme;
if (metastring && highlightLinesRangeRegex.test(metastring)) {
const highlightLinesRange = metastring.match(highlightLinesRangeRegex)[1];
@@ -38,6 +129,13 @@ export default ({ children, className: languageClassName, metastring }) => {
.filter((n) => n > 0);
}
if (metastring && codeBlockTitleRegex.test(metastring)) {
codeBlockTitle = metastring
.match(codeBlockTitleRegex)[0]
.split("title=")[1]
.replace(/"+/g, "");
}
useEffect(() => {
let clipboard;
@@ -61,28 +159,95 @@ export default ({ children, className: languageClassName, metastring }) => {
language = prism.defaultLanguage;
}
// const handleCopyCode = () => {
// window.getSelection().empty();
// setShowCopied(true);
// only declaration OR directive highlight can be used for a block
let code = children.replace(/\n$/, "");
if (highlightLines.length === 0 && language !== undefined) {
let range = "";
const directiveRegex = highlightDirectiveRegex(language);
// go through line by line
const lines = children.replace(/\n$/, "").split("\n");
let blockStart;
// loop through lines
for (let index = 0; index < lines.length; ) {
const line = lines[index];
// adjust for 0-index
const lineNumber = index + 1;
const match = line.match(directiveRegex);
if (match !== null) {
const directive = match
.slice(1)
.reduce((final, item) => final || item, undefined);
switch (directive) {
case "highlight-next-line":
range += `${lineNumber},`;
break;
// setTimeout(() => setShowCopied(false), 2000);
// };
case "highlight-start":
blockStart = lineNumber;
break;
case "highlight-end":
range += `${blockStart}-${lineNumber - 1},`;
break;
default:
break;
}
lines.splice(index, 1);
} else {
// lines without directives are unchanged
index += 1;
}
}
highlightLines = rangeParser.parse(range);
code = lines.join("\n");
}
const handleCopyCode = () => {
window.getSelection().empty();
setShowCopied(true);
setTimeout(() => setShowCopied(false), 2000);
};
return (
<Highlight
{...defaultProps}
theme={prism.theme || defaultTheme}
code={children.trim()}
key={mounted}
theme={prismTheme}
code={code}
language={language}
>
{({ className, style, tokens, getLineProps, getTokenProps }) => (
<div className={styles.codeBlockWrapper}>
<pre
ref={target}
className={classnames(className, styles.codeBlock)}
style={style}
<>
{codeBlockTitle && (
<div style={style} className={styles.codeBlockTitle}>
{codeBlockTitle}
</div>
)}
<div className={styles.codeBlockContent}>
{/* <button
ref={button}
type="button"
aria-label="Copy code to clipboard"
className={classnames(styles.copyButton, {
[styles.copyButtonWithTitle]: codeBlockTitle,
})}
onClick={handleCopyCode}>
{showCopied ? 'Copied' : 'Copy'}
</button> */}
<div
tabIndex="0"
className={classnames(className, styles.codeBlock, {
[styles.codeBlockWithTitle]: codeBlockTitle,
})}
>
<div ref={target} className={styles.codeBlockLines} style={style}>
{tokens.map((line, i) => {
if (line.length === 1 && line[0].content === "") {
line[0].content = "\n"; // eslint-disable-line no-param-reassign
}
const lineProps = getLineProps({ line, key: i });
if (highlightLines.includes(i + 1)) {
@@ -97,17 +262,10 @@ export default ({ children, className: languageClassName, metastring }) => {
</div>
);
})}
</pre>
{/* <button
ref={button}
type="button"
aria-label="Copy code to clipboard"
className={styles.copyButton}
onClick={handleCopyCode}
>
{showCopied ? "Copied" : "Copy"}
</button> */}
</div>
</div>
</div>
</>
)}
</Highlight>
);

60
docs/src/theme/CodeBlock/styles.module.css Executable file → Normal file
View File

@@ -1,31 +1,41 @@
/**
* Copyright (c) 2017-present, Facebook, Inc.
* Copyright (c) Facebook, Inc. and its affiliates.
*
* This source code is licensed under the MIT license found in the
* LICENSE file in the root directory of this source tree.
*/
.codeBlock {
margin-bottom: 0;
overflow: hidden;
overflow-wrap: break-word;
white-space: pre-wrap;
}
.codeBlockWrapper {
.codeBlockContent {
position: relative;
}
.codeBlockWrapper:hover > .copyButton {
visibility: visible;
opacity: 1;
.codeBlockTitle {
font-family: var(--ifm-font-family-monospace);
font-weight: bold;
padding: var(--ifm-pre-padding);
border-bottom: 1px solid var(--ifm-color-emphasis-200);
width: 100%;
border-top-left-radius: var(--ifm-global-radius);
border-top-right-radius: var(--ifm-global-radius);
}
.codeBlock {
overflow: auto;
border-radius: var(--ifm-global-radius);
}
.codeBlockWithTitle {
border-top-left-radius: 0;
border-top-right-radius: 0;
border-bottom-left-radius: var(--ifm-global-radius);
border-bottom-right-radius: var(--ifm-global-radius);
}
.copyButton {
background: rgb(1, 22, 39);
border: 1px solid rgb(214, 222, 235);
background: rgba(0, 0, 0, 0.3);
border: none;
border-radius: var(--ifm-global-radius);
color: rgb(214, 222, 235);
color: var(--ifm-color-content);
cursor: pointer;
line-height: 12px;
opacity: 0;
@@ -38,3 +48,23 @@
transition: opacity 200ms ease-in-out, visibility 200ms ease-in-out,
bottom 200ms ease-in-out;
}
.copyButtonWithTitle {
top: calc(var(--ifm-pre-padding));
}
.codeBlockTitle:hover + .codeBlockContent .copyButton,
.codeBlockContent:hover > .copyButton {
visibility: visible;
opacity: 1;
}
.codeBlockLines {
font-family: var(--ifm-font-family-monospace);
font-size: inherit;
line-height: var(--ifm-pre-line-height);
white-space: pre;
float: left;
min-width: 100%;
padding: var(--ifm-pre-padding);
}

21
docs/yarn.lock
View File

@@ -901,7 +901,7 @@
resolved "https://registry.yarnpkg.com/@csstools/convert-colors/-/convert-colors-1.4.0.tgz#ad495dc41b12e75d588c6db8b9834f08fa131eb7"
integrity sha512-5a6wqoJV/xEdbRNKVo6I4hO3VjyDq//8q2f9I6PBAvMesJHFauXDorcNCsr9RzvsZnaWi5NYCcfyqP1QeFHFbw==
"@docusaurus/core@^2.0.0-alpha.43":
"@docusaurus/core@^2.0.0-alpha.50":
version "2.0.0-alpha.50"
resolved "https://registry.yarnpkg.com/@docusaurus/core/-/core-2.0.0-alpha.50.tgz#4631efd9956a95aff29a6dfc9b3afffbcf6939e4"
integrity sha512-lNvft+di325Ww3/S/kgbJmDmZF6OgJc3gM5zE8Lcl2Hqa6gZ6INIsGhnGxIX5Of1apliWGRVSojEF+mxf0BE1g==
@@ -1026,14 +1026,6 @@
resolved "https://registry.yarnpkg.com/@docusaurus/plugin-google-gtag/-/plugin-google-gtag-2.0.0-alpha.50.tgz#4b69c23ef6818f96e6a13588c0e53f43ff264611"
integrity sha512-fdW6ycdnLbWah31vx1e8/n4oopwmo5H89zzC9xVsJB0snBPQnMNbuZ82ob9TXYN57JcnK5bZeVPR/RYiAh0CWQ==
"@docusaurus/plugin-sitemap@^2.0.0-alpha.37":
version "2.0.0-alpha.37"
resolved "https://registry.yarnpkg.com/@docusaurus/plugin-sitemap/-/plugin-sitemap-2.0.0-alpha.37.tgz#174fa03e7184db2971a491849b27e33f577a26b4"
integrity sha512-IF4uk2dcm1TFm9Lu9OOOk1QaLEeoUb6LXvvweKP+Usuw4OFfUcEd7KBJi2/mDSm+Ud3EenoQOENywNbKiLSzvg==
dependencies:
"@docusaurus/types" "^2.0.0-alpha.37"
sitemap "^3.2.2"
"@docusaurus/plugin-sitemap@^2.0.0-alpha.50":
version "2.0.0-alpha.50"
resolved "https://registry.yarnpkg.com/@docusaurus/plugin-sitemap/-/plugin-sitemap-2.0.0-alpha.50.tgz#a9ab066286e96ef7ef51cdadb0429562d95514e0"
@@ -1042,7 +1034,7 @@
"@docusaurus/types" "^2.0.0-alpha.50"
sitemap "^3.2.2"
"@docusaurus/preset-classic@^2.0.0-alpha.43":
"@docusaurus/preset-classic@^2.0.0-alpha.50":
version "2.0.0-alpha.50"
resolved "https://registry.yarnpkg.com/@docusaurus/preset-classic/-/preset-classic-2.0.0-alpha.50.tgz#56a3ca2b7d7a01c410009309fed7d57a67bb8788"
integrity sha512-SrVE95VNOY/X5Cc7ZL175TiCNjW50PEVoGVp/Y86/RAQEq7Wm5Bi32jFAcsjndbTOqKaEhRikSkqEQipbrF8GA==
@@ -1081,15 +1073,6 @@
classnames "^2.2.6"
docsearch.js "^2.6.3"
"@docusaurus/types@^2.0.0-alpha.37":
version "2.0.0-alpha.37"
resolved "https://registry.yarnpkg.com/@docusaurus/types/-/types-2.0.0-alpha.37.tgz#e14b8758cfefab5235c5ec190c489dd32cb7a8b8"
integrity sha512-t0bwfUQLEY6FGZX1OGhB29y7OQFAzqmNfP/UewUWOb/OiG5HBZ/r7OfwOH1dfmbjRJD99eHA3r4br8jwuvQfPg==
dependencies:
"@types/webpack" "^4.41.0"
commander "^4.0.1"
querystring "0.2.0"
"@docusaurus/types@^2.0.0-alpha.50":
version "2.0.0-alpha.50"
resolved "https://registry.yarnpkg.com/@docusaurus/types/-/types-2.0.0-alpha.50.tgz#0ea5dde077faa2e70a694eb7562bcdf21f35bc2e"