diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1320f90 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +site diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..7942726 --- /dev/null +++ b/Makefile @@ -0,0 +1,54 @@ +##@ General + +# The help target prints out all targets with their descriptions organized +# beneath their categories. The categories are represented by '##@' and the +# target descriptions by '##'. The awk commands is responsible for reading the +# entire set of makefiles included in this invocation, looking for lines of the +# file as xyz: ## something, and then pretty-format the target and help. Then, +# if there's a line with ##@ something, that gets pretty-printed as a category. +# More info on the usage of ANSI control characters for terminal formatting: +# https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_parameters +# More info on the awk command: +# http://linuxcommand.org/lc3_adv_awk.php + +.PHONY: help +help: ## Display this help. + @awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n make \033[36m\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf " \033[36m%-25s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST) + +IMAGE ?= ghcr.io/githedgehog/hhdocs:latest +RUN = docker run --rm -it -v ${PWD}:/docs -p 8000:8000 $(IMAGE) + + +.PHONY: all +all: build + +.PHONY: docker +docker: ## Pull mkdocs docker image. + docker pull -q $(IMAGE) + +CMD ?= mkdocs + +.PHONY: run +run: docker ## Run a command in the mkdocs docker image. + $(RUN) $(CMD) + +.PHONY: build +build: docker ## Build the documentation. + $(RUN) mkdocs build + +.PHONY: serve +serve: docker ## Serve the documentation. + $(RUN) mkdocs serve -a 0.0.0.0:8000 + +.PHONY: serve-versioned +serve-versioned: docker ## Serve versioned documentation with mike. + $(RUN) mike serve -a 0.0.0.0:8000 + +RELEASE ?= dev +ALIAS ?= master + +.PHONY: deploy +deploy: docker ## Deploy documentation version with mike. + $(RUN) mike deploy -u $(RELEASE) $(ALIAS) + +# TODO we need to "deploy dev" in master and "deploy -u alpha-x latest" in release/alpha-x branches \ No newline at end of file diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 0000000..7130080 --- /dev/null +++ b/docs/.pages @@ -0,0 +1,12 @@ +# https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin +nav: + - introduction.md + - getting-started + - concepts + - Wiring Diagram: wiring + - Install & Upgrade: install-upgrade + - User Guide: user-guide + - Reference: reference + - Troubleshooting: troubleshooting + - ... + - contribute diff --git a/docs/assets/favicon.ico b/docs/assets/favicon.ico new file mode 100644 index 0000000..e7c4865 Binary files /dev/null and b/docs/assets/favicon.ico differ diff --git a/docs/assets/logo.webp b/docs/assets/logo.webp new file mode 100644 index 0000000..f1ec1c7 Binary files /dev/null and b/docs/assets/logo.webp differ diff --git a/docs/concepts/overview.md b/docs/concepts/overview.md new file mode 100644 index 0000000..639d880 --- /dev/null +++ b/docs/concepts/overview.md @@ -0,0 +1 @@ +# Concepts \ No newline at end of file diff --git a/docs/contribute/.pages b/docs/contribute/.pages new file mode 100644 index 0000000..ca4c62d --- /dev/null +++ b/docs/contribute/.pages @@ -0,0 +1,4 @@ +nav: + - overview.md + - docs.md + - ... diff --git a/docs/contribute/docs.md b/docs/contribute/docs.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/contribute/overview.md b/docs/contribute/overview.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md new file mode 100644 index 0000000..8b3a794 --- /dev/null +++ b/docs/getting-started/overview.md @@ -0,0 +1 @@ +# Getting Started \ No newline at end of file diff --git a/docs/install-upgrade/overview.md b/docs/install-upgrade/overview.md new file mode 100644 index 0000000..4bba659 --- /dev/null +++ b/docs/install-upgrade/overview.md @@ -0,0 +1 @@ +# Overview \ No newline at end of file diff --git a/docs/install-upgrade/requirements.md b/docs/install-upgrade/requirements.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/install-upgrade/supported-devices.md b/docs/install-upgrade/supported-devices.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/introduction.md b/docs/introduction.md new file mode 100644 index 0000000..4836a4c --- /dev/null +++ b/docs/introduction.md @@ -0,0 +1,165 @@ +# Welcome to MkDocs + +For full documentation visit [mkdocs.org](https://www.mkdocs.org). + +## Commands + +* `mkdocs new [dir-name]` - Create a new project. +* `mkdocs serve` - Start the live-reloading docs server. +* `mkdocs build` - Build the documentation site. +* `mkdocs -h` - Print help message and exit. + +## Project layout + + mkdocs.yml # The configuration file. + docs/ + index.md # The documentation homepage. + ... # Other markdown pages, images and other files. + + +## Examples + +https://squidfunk.github.io/mkdocs-material/reference/ + +The HTML specification is maintained by the W3C. + +*[HTML]: Hyper Text Markup Language + +W3C abbr coming from includes/abbreviations.md + + +https://squidfunk.github.io/mkdocs-material/reference/admonitions/ +https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types + +```markdown +!!! note + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod + nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor + massa, nec semper lorem quam in massa. +``` + +!!! note + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod + nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor + massa, nec semper lorem quam in massa. + +```markdown +!!! info inline end "Lorem ipsum" + + Lorem ipsum dolor sit amet, consectetur + adipiscing elit. Nulla et euismod nulla. + Curabitur feugiat, tortor non consequat + finibus, justo purus auctor massa, nec + semper lorem quam in massa. +``` + +!!! info end "Lorem ipsum" + + Lorem ipsum dolor sit amet, consectetur + adipiscing elit. Nulla et euismod nulla. + Curabitur feugiat, tortor non consequat + finibus, justo purus auctor massa, nec + semper lorem quam in massa. + +``` py +import tensorflow as tf +``` + +``` py title="bubble_sort.py" hl_lines="2 3" linenums="1" +def bubble_sort(items): + for i in range(len(items)): + for j in range(len(items) - 1 - i): + if items[j] > items[j + 1]: + items[j], items[j + 1] = items[j + 1], items[j] +``` + +``` yaml +theme: + features: + - content.code.annotate # (1) +``` + +1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted + text__, images, ... basically anything that can be written in Markdown. + + + +=== "C" + + ``` c + #include + + int main(void) { + printf("Hello world!\n"); + return 0; + } + ``` + +=== "C++" + + ``` c++ + #include + + int main(void) { + std::cout << "Hello world!" << std::endl; + return 0; + } + ``` + + +| Method | Description | +| :---------- | :----------------------------------- | +| `GET` | :material-check: Fetch resource | +| `PUT` | :material-check-all: Update resource | +| `DELETE` | :material-close: Delete resource | + + +``` mermaid +graph LR + A[Start] --> B{Error?}; + B -->|Yes| C[Hmm...]; + C --> D[Debug]; + D --> B; + B ---->|No| E[Yay!]; +``` + +``` mermaid +sequenceDiagram + autonumber + Alice->>John: Hello John, how are you? + loop Healthcheck + John->>John: Fight against hypochondria + end + Note right of John: Rational thoughts! + John-->>Alice: Great! + John->>Bob: How about you? + Bob-->>John: Jolly good! +``` + +Text can be {--deleted--} and replacement text {++added++}. This can also be +combined into {~~one~>a single~~} operation. {==Highlighting==} is also +possible {>>and comments can be added inline<<}. + +{== + +Formatting can also be applied to blocks by putting the opening and closing +tags on separate lines and adding new lines between the tags and the content. + +==} + +++ctrl+alt+del++ + + +``` markdown +:fontawesome-regular-face-laugh-wink: +:fontawesome-brands-twitter:{ .twitter } +``` + +:fontawesome-regular-face-laugh-wink: +:fontawesome-brands-twitter:{ .twitter } + +https://github.com/mkdocstrings/autorefs + +(test url)[https://test.githedgehog.com] \ No newline at end of file diff --git a/docs/reference/api.md b/docs/reference/api.md new file mode 100644 index 0000000..b2fad2e --- /dev/null +++ b/docs/reference/api.md @@ -0,0 +1 @@ +# API Reference \ No newline at end of file diff --git a/docs/reference/cli.md b/docs/reference/cli.md new file mode 100644 index 0000000..8341cf3 --- /dev/null +++ b/docs/reference/cli.md @@ -0,0 +1 @@ +# CLI reference \ No newline at end of file diff --git a/docs/troubleshooting/overview.md b/docs/troubleshooting/overview.md new file mode 100644 index 0000000..64a80c8 --- /dev/null +++ b/docs/troubleshooting/overview.md @@ -0,0 +1 @@ +# Troubleshooting \ No newline at end of file diff --git a/docs/user-guide/.pages b/docs/user-guide/.pages new file mode 100644 index 0000000..6cf14ec --- /dev/null +++ b/docs/user-guide/.pages @@ -0,0 +1,5 @@ +nav: + - overview.md + - vpc.md + - harvester.md + - ... diff --git a/docs/user-guide/harvester.md b/docs/user-guide/harvester.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/user-guide/overview.md b/docs/user-guide/overview.md new file mode 100644 index 0000000..4bba659 --- /dev/null +++ b/docs/user-guide/overview.md @@ -0,0 +1 @@ +# Overview \ No newline at end of file diff --git a/docs/user-guide/vpc.md b/docs/user-guide/vpc.md new file mode 100644 index 0000000..3eca96f --- /dev/null +++ b/docs/user-guide/vpc.md @@ -0,0 +1 @@ +# VPCs \ No newline at end of file diff --git a/docs/wiring/.pages b/docs/wiring/.pages new file mode 100644 index 0000000..ed3e32d --- /dev/null +++ b/docs/wiring/.pages @@ -0,0 +1,4 @@ +nav: + - overview.md + - clos.md + - ... diff --git a/docs/wiring/clos.md b/docs/wiring/clos.md new file mode 100644 index 0000000..fc14d2d --- /dev/null +++ b/docs/wiring/clos.md @@ -0,0 +1,19 @@ +# Clos + +Placeholder: + +```mermaid +flowchart TD + spine1 --- leaf1 + spine2 --- leaf1 + spine1 --- leaf2 + spine2 --- leaf2 + spine1 --- leaf3 + spine2 --- leaf3 + spine1 --- leaf4 + spine2 --- leaf4 + leaf1 --- edge1 + leaf2 --- edge1 + leaf3 --- edge2 + leaf4 --- edge2 +``` \ No newline at end of file diff --git a/docs/wiring/overview.md b/docs/wiring/overview.md new file mode 100644 index 0000000..3038553 --- /dev/null +++ b/docs/wiring/overview.md @@ -0,0 +1 @@ +# Wiring Diagram \ No newline at end of file diff --git a/hhdocs/Dockerfile b/hhdocs/Dockerfile new file mode 100644 index 0000000..c8ab0e7 --- /dev/null +++ b/hhdocs/Dockerfile @@ -0,0 +1,10 @@ +FROM squidfunk/mkdocs-material + +COPY requirements.txt /requirements.txt +RUN pip install -r /requirements.txt + +COPY gitconfig /root/.gitconfig + +COPY entrypoint.sh /entrypoint.sh +ENTRYPOINT ["/entrypoint.sh"] + diff --git a/hhdocs/entrypoint.sh b/hhdocs/entrypoint.sh new file mode 100755 index 0000000..f626711 --- /dev/null +++ b/hhdocs/entrypoint.sh @@ -0,0 +1,17 @@ +#!/bin/sh + +if [ "$#" -eq "0" ]; then + echo "Only mkdocs and mike commands are available" + exit 1 +fi + +if [ "$1" = "mkdocs" ]; then + shift + mkdocs "$@" +elif [ "$1" = "mike" ]; then + shift + mike "$@" +else + echo "Only mkdocs and mike commands are available" + exit 1 +fi \ No newline at end of file diff --git a/hhdocs/gitconfig b/hhdocs/gitconfig new file mode 100644 index 0000000..116cdb6 --- /dev/null +++ b/hhdocs/gitconfig @@ -0,0 +1,7 @@ +[user] + name = HHDocs + email = hhdocs@githedgehog.com + +[safe] + directory = /docs + directory = /site \ No newline at end of file diff --git a/hhdocs/requirements.txt b/hhdocs/requirements.txt new file mode 100644 index 0000000..c14ca13 --- /dev/null +++ b/hhdocs/requirements.txt @@ -0,0 +1,7 @@ +mkdocs-glightbox +mkdocs-autorefs +mkdocs-git-revision-date-localized-plugin +mkdocs-redirects +mkdocs-awesome-pages-plugin +mkdocs-htmlproofer-plugin +mike \ No newline at end of file diff --git a/includes/abbreviations.md b/includes/abbreviations.md new file mode 100644 index 0000000..79898ef --- /dev/null +++ b/includes/abbreviations.md @@ -0,0 +1,4 @@ +*[HTML]: Hyper Text Markup Language +*[W3C]: World Wide Web Consortium +*[VPC]: Virtual Private Cloud +*[HHFab]: Hedgehog Fabricator - a tool for building Hedgehog Fabric diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..36eb235 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,110 @@ +site_name: Open Network Fabric +site_url: https://docs.githedgehog.com/ +site_description: Hedgehog Open Network Fabric Documentation +site_author: Hedgehog Authors +copyright: ©2023 Hedgehog + +theme: + name: material + logo: assets/logo.webp + favicon: assets/favicon.ico + custom_dir: overrides + features: + - content.action.edit + - navigation.instant + - navigation.instant.progress + - navigation.tracking + # - navigation.sections + # - navigation.tabs # TODO Do we need them or just everything in the sidebar is better? + # we can hide sidebars for the tabs where it's not needed + # https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#hiding-the-sidebars + - navigation.expand + - toc.follow + - navigation.top + - search.suggest + - search.highlight + - search.share + - content.code.copy + - content.code.annotate + - content.tabs.link + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + toggle: + icon: material/weather-night + name: Switch to dark mode + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + toggle: + icon: material/weather-sunny + name: Switch to light mode + +extra: + homepage: https://docs.githedgehog.com + version: + provider: mike + default: latest + social: + - icon: fontawesome/brands/linkedin + link: https://www.linkedin.com/company/githedgehog/ + + # consent: + # title: Cookie consent + # description: >- + # We use cookies to recognize your repeated visits and preferences, as well + # as to measure the effectiveness of our documentation and whether users + # find what they're searching for. With your consent, you're helping us to + # make our documentation better. + +repo_url: https://github.com/githedgehog/docs +repo_name: githedgehog/docs +# edit_uri: edit/master/docs/ + +plugins: + - search + - glightbox + - autorefs + - awesome-pages: + collapse_single_pages: true + sort_type: natural + order_by: title + - git-revision-date-localized: + enable_creation_date: true + # - htmlproofer # https://github.com/manuzhang/mkdocs-htmlproofer-plugin + +markdown_extensions: + - abbr + - attr_list + - admonition + - tables + - pymdownx.details + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - pymdownx.snippets: + auto_append: + - includes/abbreviations.md + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.tabbed: + alternate_style: true + - pymdownx.critic + - pymdownx.caret + - pymdownx.keys + - pymdownx.mark + - pymdownx.tilde + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + +watch: + - includes + - overrides diff --git a/overrides/main.html b/overrides/main.html new file mode 100644 index 0000000..35591d6 --- /dev/null +++ b/overrides/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block outdated %} + You're not viewing the latest version. + + Click here to go to latest. + +{% endblock %} \ No newline at end of file