Skip to content

Commit 0fae3aa

Browse files
nsaxena16nsaxena16
committed
docs: add SONiC Sphinx docs
Signed-off-by: Nitin Saxena <nsaxena@marvell.com>
1 parent c2e5fcc commit 0fae3aa

36 files changed

Lines changed: 4113 additions & 34 deletions

‎.cursor/rules/sonic-docs.mdc‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
---
2+
description: Conventions for the Sphinx docs site under docs/ (structure, naming, styling, build/verify workflow)
3+
globs: docs/**
4+
alwaysApply: false
5+
---
6+
7+
# Prestera SONiC Docs Site Conventions
8+
9+
Sphinx + MyST (Markdown) + `pydata_sphinx_theme` + `sphinx_design`. SONiC content
10+
lives under `docs/SONIC/`, authored in Markdown; the landing page is
11+
`docs/index.rst` (reStructuredText, needed for the `sphinx_design` grid).
12+
13+
## Folder & Page Structure
14+
15+
- Top-level nav sections each have a **folder with `index.md`** hub page,
16+
listed in `docs/index.rst`'s hidden top `toctree`: **About**, **Getting
17+
Started**, **For Developers**, **Releases**, **Collaborate**. (**Solutions**
18+
was removed from navigation.)
19+
- A sub-topic gets its own **sub-folder with `index.md`** only if it may need
20+
further nested sub-pages (e.g. `getting-started/marvell-prestera/index.md`).
21+
Otherwise a single leaf page is a **flat `.md` file** in the parent folder.
22+
- Hub `index.md` pages use a **visible** `{toctree}` with `:caption: In this
23+
section`, so the page body links to its sub-pages.
24+
- Placeholder pages: `# H1` + `*(Content coming soon.)*` only — don't invent
25+
content.
26+
- Images live in `images/` at the **section folder** level (e.g.
27+
`docs/SONIC/about/images/sonic_architecture.svg`). Shared assets go in
28+
`docs/_static/images/`.
29+
- Keep `docs/README.md` in sync when folders are added/moved/renamed.
30+
31+
## Navigation (`docs/_templates/navbar-nav.html`)
32+
33+
- Custom navbar replaces the theme default: each top-level section is a
34+
**hover dropdown** listing its sub-pages (hand-maintained; must match each
35+
section's `{toctree}`).
36+
- Dropdown visibility uses `docs/_static/js/navbar-dropdown.js` (`.show-dropdown`
37+
class) plus CSS in `custom.css` — pure CSS `:hover` alone is unreliable
38+
against theme specificity.
39+
- Section titles: **About** (not "About Prestera SONiC"), **Getting Started**,
40+
**For Developers**, **Releases**, **Collaborate**.
41+
- **Releases** is a top-level section (`SONIC/releases/`), not under About.
42+
- **Protocols** was removed from the For Developers dropdown.
43+
44+
## Landing Page (`docs/index.rst`)
45+
46+
- Grid tiles use `:link-type: doc`. Current tiles (3×2):
47+
- Row 1: What is SONiC, Why Prestera SONiC, Marvell Prestera Platforms
48+
- Row 2: Deploy Prestera SONiC, How to Contribute, Raise Issues
49+
- **Releases** is not a landing tile (it is a top-level nav section).
50+
- Tile titles must stay short (`white-space: nowrap` on card titles).
51+
- Filenames/slugs use kebab-case; displayed text is Title Case.
52+
53+
## Branding & Navbar Logo
54+
55+
- User-facing product name in page content and tiles: **Prestera SONiC** (not
56+
"Marvell SONiC" as the product brand).
57+
- **Navbar logo (top-left)**: keep the **original combined** raster only —
58+
`html_logo = "_static/images/marvell_sonic_logo.png"` (Marvell mark | SONiC
59+
wordmark). Do **not** add `logo.text` in `html_theme_options` or swap in
60+
`marvell_logo.png`; users asked to keep this SONiC branding in the navbar.
61+
- `project` in `conf.py` may still be `Prestera SONiC` for site metadata; that
62+
is separate from the navbar image.
63+
- `marvell-<original submodule name>` in git is a submodule naming scheme, not
64+
the product brand.
65+
66+
## Prose & Typography (`docs/_static/css/custom.css`)
67+
68+
- All headings (h1–h6) site-wide: plain `sans-serif`, non-bold.
69+
- **Inline literals** (single backticks in Markdown): render as *italic prose*
70+
via site-wide CSS on `.bd-article code.literal` — not highlighted monospace.
71+
Do **not** use backticks for emphasis in new prose; prefer `*italic*` in
72+
Markdown. Fenced code blocks (` ```bash ` etc.) keep monospace styling.
73+
- **Build Arguments** and similar reference sections: use **`**ARG=value**`**
74+
for flags (no backticks inside bold). Use `*italic*` for technical names
75+
(`syncd-rpc`, `make configure`, etc.). Use `**<PLACEHOLDER>**` for
76+
angle-bracket placeholders such as `BUILD_CACHE_PATH`.
77+
- All table cells are centered globally. Prefer Markdown pipe tables; use raw
78+
HTML only when `colspan`/`rowspan` is required (e.g. protocols table before
79+
hardened columns were removed).
80+
81+
## Build Page Conventions (`SONIC/getting-started/build/index.md`)
82+
83+
- **Build Cache** section + **`BUILD_CACHE_PATH`** subsection; link to
84+
**Caching** under Build Arguments for flag details.
85+
- ARM64 / AMD64 build sections link to the [Prestera platforms
86+
table](../getting-started/marvell-prestera/index.md#prestera-sonic-support)
87+
instead of listing SKUs inline.
88+
- `make configure` / `make` command blocks: backslashes only at line ends;
89+
refer to Build Arguments and upstream SONiC README for additional flags.
90+
91+
## Architecture Diagram (`SONIC/about/images/sonic_architecture.svg`)
92+
93+
- Redis DB: container with six DB boxes in **2 columns × 3 rows** (no ellipsis).
94+
- swss: five manager sub-boxes + ellipsis for more managers.
95+
- syncd (left) and gbsyncd (right) with a wide solid double-arrow between them.
96+
- gbsyncd → PHY: **purple dashed** path from gbsyncd centre at `y=404`
97+
(parallel to syncd↔gbsyncd arrow), horizontal to SAI API right edge, then
98+
**only along outside edges** of the SAI API dashed box (no line inside the
99+
rectangle), then downward parallel to the solid syncd → ASIC path (offset so
100+
both lines stay visible).
101+
- Switch ASIC and PHY at bottom with solid double-arrow between them.
102+
- XML comments must not contain `--` (invalid in SVG/XML comments).
103+
104+
## Release Pages (`docs/SONIC/releases/`)
105+
106+
- Top-level **Releases** section (moved out of About). Hub:
107+
`SONIC/releases/index.md`; per-release pages under the same folder.
108+
- Naming image: `../about/images/release-naming-convention.svg`.
109+
- Table + hidden `{toctree}` for each release page; link to Prestera SONiC
110+
Repositories with `../developers/...` from release pages.
111+
112+
## Build & Verify
113+
114+
From `docs/`:
115+
116+
```bash
117+
rm -rf _build
118+
source .venv/bin/activate
119+
sphinx-build -b html . _build/html
120+
```
121+
122+
- Run `rm -rf _build` and build as **separate steps** after commands that may
123+
fail (e.g. `pkill`).
124+
- Version-switcher fetch warning is harmless locally.
125+
- Restart `python3 -m http.server` in `_build/html` after rebuild; kill stale
126+
servers with `pkill -f "http.server"` if the browser shows old assets.
127+
- Hard refresh (Ctrl+Shift+R) when verifying logo/SVG/CSS changes.
128+
129+
## Version Switcher / Deployment
130+
131+
- `docs/_static/versions.json` and `conf.py` `switcher.json_url` use fixed
132+
absolute URLs. See `.github/workflows/docs.yml`.

‎.github/workflows/docs.yml‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
name: Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- "docs/**"
9+
- ".github/workflows/docs.yml"
10+
pull_request:
11+
paths:
12+
- "docs/**"
13+
- ".github/workflows/docs.yml"
14+
workflow_dispatch:
15+
16+
permissions:
17+
contents: read
18+
pages: write
19+
id-token: write
20+
21+
# Only one concurrent deployment, but do not cancel in-progress runs as
22+
# we want these to complete.
23+
concurrency:
24+
group: "pages"
25+
cancel-in-progress: false
26+
27+
jobs:
28+
build:
29+
runs-on: ubuntu-latest
30+
steps:
31+
- name: Checkout
32+
uses: actions/checkout@v4
33+
34+
- name: Set up Python
35+
uses: actions/setup-python@v5
36+
with:
37+
python-version: "3.12"
38+
39+
- name: Install dependencies
40+
run: pip install -r docs/requirements.txt
41+
42+
- name: Build docs
43+
run: make -C docs html
44+
45+
# Deploy this build under a version-named subfolder (currently just
46+
# "master", the latest/default version) rather than at the site root,
47+
# so the URL scheme matches the per-release layout in docs/_static/versions.json
48+
# and leaves room for other versions (e.g. release branches) to be
49+
# added alongside it later without restructuring anything. A single
50+
# top-level versions.json (not duplicated per version) is what the
51+
# version-switcher dropdown fetches, so every version's dropdown
52+
# always shows the same, current list.
53+
- name: Assemble versioned Pages site
54+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
55+
run: |
56+
set -euo pipefail
57+
site=pages-site
58+
rm -rf "$site"
59+
mkdir -p "$site/master"
60+
cp -r docs/_build/html/. "$site/master/"
61+
cp docs/_static/versions.json "$site/versions.json"
62+
cat > "$site/index.html" <<'EOF'
63+
<!DOCTYPE html>
64+
<html lang="en">
65+
<head>
66+
<meta charset="utf-8">
67+
<meta http-equiv="refresh" content="0; url=master/">
68+
<link rel="canonical" href="master/">
69+
<title>Marvell SONiC</title>
70+
</head>
71+
<body>
72+
<p>Redirecting to the <a href="master/">latest docs</a>&hellip;</p>
73+
</body>
74+
</html>
75+
EOF
76+
77+
- name: Upload artifact
78+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
79+
uses: actions/upload-pages-artifact@v3
80+
with:
81+
path: pages-site
82+
83+
deploy:
84+
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
85+
needs: build
86+
runs-on: ubuntu-latest
87+
environment:
88+
name: github-pages
89+
url: ${{ steps.deployment.outputs.page_url }}
90+
steps:
91+
- name: Deploy to GitHub Pages
92+
id: deployment
93+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 4 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,5 @@
1-
# SONiC Support for Marvell Prestera Platforms
2-
3-
SONiC platform enablement for switches built on the Marvell Prestera (AC5X / AC5P) and Falcon (98CX85xx) switching silicon, including the Marvell Prestera SAI, syncd/saiserver dockers, and platform API implementations.
4-
5-
## Table of Contents
6-
7-
- [Overview](#overview)
8-
- [Platforms Supported](#platforms-supported)
9-
- [Release Notes](#release-notes)
10-
11-
## Overview
12-
13-
This repository contains the SONiC build integration for the Marvell Prestera family of switching platforms. It includes:
14-
15-
- **SAI / syncd**: `docker-syncd-mrvl-prestera` (and RPC variant) built against the Marvell Prestera SAI implementation.
16-
17-
## Platforms Supported
18-
19-
| Platform Family | Board / SKU | Architecture | ONIE Platform String |
20-
|---|---|---|---|
21-
| Marvell AC5X | RD98DX35xx | arm64 | `arm64-marvell_rd98DX35xx-r0` |
22-
| Marvell AC5X + CN9131 | RD98DX35xx-CN9131 | arm64 | `arm64-marvell_rd98DX35xx_cn9131-r0` |
23-
| Marvell AC5P + CN9131 | RD98DX45xx-CN9131 | arm64 | `arm64-marvell_rd98DX45xx_cn9131-r0` |
24-
| Marvell AC5X (x86 host CPU) | RD98DX35xx | amd64 | `x86_64-marvell_rd98DX35xx-r0` |
25-
| Marvell Falcon | DB98CX8580-32CD | amd64 | `x86_64-marvell_db98cx8580_32cd-r0` |
26-
| Marvell Falcon | DB98CX8540-16CD | amd64 | `x86_64-marvell_db98cx8540_16cd-r0` |
27-
| Marvell Falcon | DB98CX8514-10CC | amd64 | `x86_64-marvell_db98cx8514_10cc-r0` |
28-
| Marvell Falcon | DB98CX8522-10CC | amd64 | `x86_64-marvell_db98cx8522_10cc-r0` |
29-
30-
## Release Notes
31-
32-
| SONiC Release Branch | Status | Highlights | More Info |
33-
|---|---|---|---|
34-
| `rls-202511` | Active | Latest stable support for AC5X/AC5P/Falcon/ platforms. | [Link](https://github.com/MarvellEmbeddedProcessors/dao/releases) |
1+
Marvell Prestera SONiC
2+
======================
353

4+
SONiC for Marvell Prestera (AC5X / AC5P) and Falcon (98CX85xx) switching
5+
silicon.

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
_build/
2+
.venv/

‎docs/Makefile‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Minimal Makefile for the Sphinx documentation.
2+
3+
SPHINXOPTS ?=
4+
SPHINXBUILD ?= sphinx-build
5+
SOURCEDIR = .
6+
BUILDDIR = _build
7+
8+
.PHONY: help clean html livehtml
9+
10+
help:
11+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
12+
13+
html:
14+
@$(SPHINXBUILD) -W -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)
15+
16+
clean:
17+
rm -rf "$(BUILDDIR)"
18+
19+
# Requires sphinx-autobuild (not in requirements.txt, install separately).
20+
livehtml:
21+
sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS) $(O)

0 commit comments

Comments
 (0)