Skip to content

Commit a46d5c4

Browse files
sra-hubsra-hub
authored
Merge branch 'master' into DOCS-8097-Plugin-API-SSPM
2 parents 7523e41 + d2d8225 commit a46d5c4

22 files changed

Lines changed: 463 additions & 313 deletions

File tree

‎AGENTS.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# AGENTS.md
2+
3+
> **Audience** – Automated coding assistants (OpenAI Codex, Sourcegraph AMP, Windsurf, etc.). Humans are welcome to read it too!
4+
5+
---
6+
7+
## 🚀 Quick Facts
8+
9+
| Key | Value |
10+
| -------------------- | ----------------------------------------------------------------------------------------------- |
11+
| **Site** | **pan.dev** – public developer documentation for Palo Alto Networks |
12+
| **Generator** | Docusaurus **3.7.0** (static site) |
13+
| **Tooling** | Yarn 4 workspaces, Node 20 LTS (see `.nvmrc`) |
14+
| **Selective builds** | `PRODUCTS_INCLUDE` env‑var lets you build one or more products instead of the whole site (≈1 h) |
15+
16+
---
17+
18+
## 🗺️ Repository Map (top‑level)
19+
20+
| Path | Purpose |
21+
| ---------------- | ----------------------------------------------------------------------- |
22+
| `products/` | One folder per product → MDX docs, OpenAPI specs, `sidebars.{js,ts}` |
23+
| `src/pages/` | Homepage & other global landing pages – **agents SHOULD improve these** |
24+
| `src/` | Shared React + TS components, theme overrides, utilities |
25+
| `static/` | Assets copied verbatim to the final build |
26+
| `plugin-*` | Custom Docusaurus plugins (`plugin-sitemap-coveo`, GTM, etc.) |
27+
| `scripts/` | Automation helpers (e.g., `openapi-to-mdx.ts`) |
28+
| `openapi-specs/` | Raw OpenAPI JSON/YAML files fed into plugin‑openapi‑docs |
29+
| `.github/` | Workflows (self‑hosted runners, preview deploys) |
30+
31+
> **Gotcha** – Some products share a sidebar. If you omit one of those products from `PRODUCTS_INCLUDE`, the build will throw an “Unknown sidebar” error. When unsure, include the whole family (e.g., `sase,access,sdwan,scm`).
32+
33+
---
34+
35+
## 🛠️ Local Dev Cheat‑Sheet
36+
37+
```bash
38+
# Install deps (Node 20 LTS)
39+
corepack enable # enables Yarn 4 if needed
40+
yarn
41+
42+
# Full dev (slow)
43+
yarn start
44+
45+
# Fast dev – only selected products
46+
cross-env PRODUCTS_INCLUDE=panos,prisma-cloud yarn start
47+
48+
# Lint & format
49+
yarn lint && yarn format
50+
51+
# Production build (selected products)
52+
cross-env PRODUCTS_INCLUDE=panos yarn build
53+
```
54+
55+
---
56+
57+
## ✍️ Writing & Coding Guidelines
58+
59+
| ✅ **DO** | ❌ **AVOID** |
60+
| -------------------------------------------------------------------- | --------------------------------------- |
61+
| Use plain English; define acronyms on first use | Security‑jargon overload |
62+
| Add front‑matter: `id`, `title`, `sidebar_label`, `sidebar_position` | Missing or duplicate `id`s |
63+
| Keep headings hierarchical (H2 → H3 → H4) | Skipping heading levels |
64+
| Provide runnable examples (`curl`, `python`, `golang`) | Proprietary/internal endpoints |
65+
| Run `yarn format` (Prettier) before every commit | Inconsistent spacing or 100+‑char lines |
66+
| Add **alt text** for images (a11y) | Decorative images without alt text |
67+
68+
### Front‑end Conventions
69+
70+
* React functional components in **TypeScript strict mode** (see `tsconfig.json`).
71+
* Style with CSS Modules or Tailwind (theme pre‑configured).
72+
* Absolute import paths use the `@/` alias.
73+
74+
---
75+
76+
## 🤖 Common Agent Tasks
77+
78+
1. **Generate docs from OpenAPI**
79+
80+
```bash
81+
yarn openapi:generate
82+
```
83+
2. **Author / update MDX** – add file, update product sidebar, run selective build.
84+
3. **Fix links**
85+
86+
```bash
87+
yarn lint:links
88+
```
89+
4. **Improve landing pages** – edit `src/pages/index.mdx` & friends.
90+
5. **CI tweaks** – update `.github/workflows/*.yml`, keep `PRODUCTS_INCLUDE` label logic intact.
91+
92+
> Always open a PR —even for small fixes. GitHub Actions deploys a preview to Firebase for human review.
93+
94+
---
95+
96+
## 🔒 Safety & Compliance
97+
98+
* **NO SECRETS** – never commit API keys, internal hostnames, or proprietary code.
99+
* Repo is public; content must stay customer‑friendly & vendor‑neutral.
100+
* Aim for WCAG AA accessibility (semantic HTML, good contrast, alt text).
101+
102+
---
103+
104+
## 📚 Further Reading
105+
106+
* [`README.md`](./README.md) – project overview
107+
* [`CONTRIBUTING.md`](./CONTRIBUTING.md) – full contribution guide
108+
* Docusaurus docs → [https://docusaurus.io/docs](https://docusaurus.io/docs)
109+
110+
---
111+
112+
*Last updated: **2025‑06‑18***

‎docusaurus.config.ts‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ const config = {
192192
"Learn how to make the most of the PAN-OS APIs, SDKs, Expedition, Terraform, Ansible, and more.",
193193
products: [
194194
{
195-
label: "AI Runtime Security",
195+
label: "Prisma AIRS",
196196
to: "#",
197197
logoClass: "panos",
198198
docs: [
@@ -204,8 +204,8 @@ const config = {
204204
],
205205
apiDocs: [
206206
{
207-
to: "ai-runtime-security/scan/api/",
208-
label: "AI Runtime Security API",
207+
to: "prisma-airs/scan/api/",
208+
label: "Prisma AIRS API",
209209
icon: "api-doc",
210210
},
211211
],
@@ -997,8 +997,8 @@ const config = {
997997
sidebarOptions: { groupPathsBy: "tag", categoryLinkSource: "info" },
998998
},
999999
airuntimesecurity: {
1000-
specPath: "openapi-specs/ai-runtime-security/scan",
1001-
outputDir: "products/ai-runtime-security/api",
1000+
specPath: "openapi-specs/prisma-airs/scan",
1001+
outputDir: "products/prisma-airs/api/airuntimesecurity",
10021002
proxy: "https://cors.pan.dev",
10031003
sidebarOptions: { groupPathsBy: "tag", categoryLinkSource: "tag" },
10041004
},

‎openapi-specs/iot/components/securitySchemes.yaml‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,14 @@
11
securitySchemes:
2+
Bearer:
3+
scheme: bearer
4+
type: http
25
X-Key-Id:
3-
description: Your API header requires X-Key-Id for authentication.
6+
description: DEPRECATED - Your API header requires X-Key-Id for authentication.
47
type: apiKey
58
in: header
69
name: X-Key-Id
710
X-Access-Key:
8-
description: Your API header requires X-Key-Key for authentication.
11+
description: DEPRECATED - Your API header requires X-Key-Key for authentication.
912
type: apiKey
1013
in: header
1114
name: X-Access-Key

0 commit comments

Comments
 (0)