Generated documentation and website

.github/templates/api-reference-md.tmpl

@@ -0,0 +1,57 @@
+{{range .Files -}}
+# {{.Name}}
+
+{{range .Services -}}
+## {{.Name}}
+
+{{.Description}}
+
+{{range .Methods -}}
+### {{.Name}}
+
+> **rpc** {{.Name}}([{{.RequestLongType}}](../{{(printf "%s#%s" .RequestTypeFile .RequestLongType) | lower | replace "." ""}}))
+    [{{.ResponseLongType}}](../{{(printf "%s#%s" .ResponseTypeFile .ResponseLongType) | lower | replace "." ""}})
+
+{{ .Description}}
+
+{{end -}} <!-- end Methods -->
+{{end -}} <!-- end Services -->
+
+{{if .HasMessages}}
+## Messages
+{{end}} <!-- end HasMessages -->
+
+{{range .Messages}}
+### {{.LongName}}
+
+{{.Description}}
+
+{{if .HasFields -}}
+| Name | Value | Description |
+| ---- | ------ | ----------- |
+{{range .Fields -}}
+| {{if .IsOneof}}**oneof** {{.OneofDecl}}.{{end}}{{.Name}} | {{if .IsMap}}map {{else}}{{.Label}} {{end}}{{if empty .TypeFile}}{{.LongType}}{{else}}[{{.LongType}}](../{{(printf "%s#%s" .TypeFile .LongType) | lower | replace "." ""}}){{end}} | {{if .Description}}{{nobr .Description | replace "\n" "<br>"}}{{if .DefaultValue}} Default: {{.DefaultValue}}{{end}}{{end}} |
+{{end}}
+<!-- end Fields -->
+{{else}}
+Empty message.
+{{end}} <!-- end HasFields -->
+{{end}} <!-- end Messages -->
+
+{{if .HasEnums}}
+## Enums
+{{end}} <!-- end HasEnums -->
+
+{{range .Enums}}
+### {{.LongName}}
+
+{{.Description}}
+
+| Name | Value | Description |
+| ---- | ------ | ----------- |
+{{range .Values -}}
+| {{.Name}} | {{.Number}} | {{if .Description}}{{nobr .Description | replace "\n" "<br>"}}{{end}} |
+{{end}}
+<!-- end Values -->
+{{end}} <!-- end Enums -->
+{{end}} <!-- end Files -->

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: ci
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: install protobuf-compiler
+        run: sudo apt install -y protobuf-compiler
+      - uses: actions/setup-go@v4
+        with:
+          go-version: '>=1.17.0'
+      - name: install protoc-gen-doc
+        # TODO use this command instead when the PR is merged
+        # https://github.com/pseudomuto/protoc-gen-doc/pull/522
+        # run: go install github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc@latest
+        run: |
+          cd ${{github.workspace}}
+          wget https://github.com/aristanetworks/protoc-gen-doc/archive/refs/heads/feat/separate-files.zip
+          unzip separate-files.zip
+          cd protoc-gen-doc-feat-separate-files
+          make build
+      - name: generate markdown files from comments
+        # TODO remove the first argument line when the PR is merged
+        run: |
+          protoc \
+              --plugin=protoc-gen-doc=${{github.workspace}}/protoc-gen-doc-feat-separate-files/bin/protoc-gen-doc \
+              -I${{github.workspace}}/proto \
+              --doc_out=${{github.workspace}}/docs/api-reference \
+              --doc_opt=${{github.workspace}}/.github/templates/api-reference-md.tmpl,md,default,separate_files \
+              ${{github.workspace}}/proto/*.proto
+      - name: upload generated documentation as an artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: api-reference-protofiles
+          path: |
+            ${{github.workspace}}/docs/api-reference
+            !${{github.workspace}}/docs/api-reference/index.md
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs-material mkdocs-awesome-pages-plugin mdx_truly_sane_lists
+      - run: mkdocs gh-deploy --force

README.md

@@ -0,0 +1,34 @@
+# Arista's EOS SDK RPC protofiles
+
+This repository holds protofiles and documentation for EOS SDK RPC.
+
+A website with full documentation is hosted at: https://aristanetworks.github.io/eossdkrpc.
+
+## Previewing the documentation website
+
+The documentation website can be built and run locally to preview new changes.
+
+```sh
+# create and enter a python virtual environment
+$ python3 -m venv .venv
+$ source .venv/bin/activate
+
+# install dependencies
+$ pip install -r requirements.txt
+
+# run the website locally and open the preview link in a browser
+$ mkdocs serve
+[...]
+INFO     -  [04:20:07] Serving on http://127.0.0.1:8000/
+[...]
+```
+
+By default, the former does include the API reference (only guides, FAQ, and general structure/look).
+
+### Previewing the API reference
+
+The API reference is not source controlled in this repository as it gets auto-generated by the GitHub CI.
+
+After each CI run, all documentation files generated from protofiles are uploaded.
+They can be retrieved from the [GitHub UI](https://github.com/aristanetworks/eossdkrpc/actions).
+The downloaded files should then be unzipped to `docs/api-reference/`. The website can then be re-run.

docs/.pages

@@ -0,0 +1,5 @@
+nav:
+  - Home: index.md
+  - Guides: guides
+  - API reference: api-reference
+  - FAQ: faq.md

docs/api-reference/index.md

@@ -0,0 +1,8 @@
+# API reference
+
+This API reference is automatically generated from protofiles comments using the [protoc-gen-doc](https://github.com/pseudomuto/protoc-gen-doc) plugin.
+
+Anyone is welcome to signal any generation problem by [opening an issue](https://github.com/aristanetworks/eossdkrpc/issues/new) on the GitHub repository so we can fix it ASAP.
+
+Feel free to read source protofiles from the repository if the documentation is not explicit enough.
+Additionally, checking out the [guides section](../guides/) might be helpful.

docs/faq.md

@@ -0,0 +1,3 @@
+# Frequently Asked Questions
+
+⛏

docs/guides/index.md

@@ -0,0 +1,3 @@
+# Guides
+
+⛏

docs/index.md

@@ -0,0 +1,11 @@
+# Arista's EOS SDK RPC
+
+This is the official documentation for the gRPC API over Arista's EOS SDK.
+
+---
+
+Sections of interest:
+
+- [API reference](./api-reference/index.md)
+- [Guides](./guides/index.md)
+- [FAQ](./faq.md)

mkdocs.yml

@@ -0,0 +1,44 @@
+site_name: EOS SDK RPC documentation
+site_author: Arista Networks
+site_description: Arista's EOS SDK RPC documentation
+repo_name: eossdkrpc on GitHub
+repo_url: https://github.com/aristanetworks/eossdkrpc
+copyright: Copyright © 2021 Arista Networks, Inc. All rights reserved.
+docs_dir: docs/
+plugins:
+  - search # built in
+  - awesome-pages # rename and reorder sections (see the .pages file)
+extra:
+  social:
+    - icon: fontawesome/brands/github-alt
+      link: https://github.com/aristanetworks/eossdkrpc
+    - icon: fontawesome/solid/globe
+      link: https://www.arista.com
+markdown_extensions:
+  - toc:
+      permalink: "¶"
+      toc_depth: 3
+  - tables
+  - mdx_truly_sane_lists
+theme:
+  name: material
+  language: en
+  favicon: assets/favicon.ico
+  features:
+    - header.autohide
+    - navigation.tabs # tabs under header
+    - navigation.indexes # merge index.md page with section
+    - navigation.instant # toc follows scrolling
+    - navigation.top # back to top button on scrolling down
+    - navigation.footer # previous and next buttons
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      toggle:
+        icon: material/weather-night
+        name: Switch to light mode

requirements.txt

@@ -0,0 +1,29 @@
+bracex==2.3.post1
+certifi==2023.5.7
+charset-normalizer==3.2.0
+click==8.1.5
+colorama==0.4.6
+ghp-import==2.1.0
+idna==3.4
+Jinja2==3.1.2
+Markdown==3.3.7
+MarkupSafe==2.1.3
+mdx-truly-sane-lists==1.3
+mergedeep==1.3.4
+mkdocs==1.4.3
+mkdocs-awesome-pages-plugin==2.9.1
+mkdocs-material==9.1.19
+mkdocs-material-extensions==1.1.1
+natsort==8.4.0
+packaging==23.1
+Pygments==2.15.1
+pymdown-extensions==10.1
+python-dateutil==2.8.2
+PyYAML==6.0.1
+pyyaml_env_tag==0.1
+regex==2023.6.3
+requests==2.31.0
+six==1.16.0
+urllib3==2.0.3
+watchdog==3.0.0
+wcmatch==8.4.1