Skip to content

ci: Run docs generation on all changes #65

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BaptisteGi merged 10 commits into from
Feb 6, 2026
Merged

ci: Run docs generation on all changes #65

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
609e528
ci: Run docs generation on all changes
petercrocker Jan 28, 2026
dedfbf3
Auto push documentation change
BaptisteGi Jan 29, 2026
142e0f8
Adjust curl command
BaptisteGi Jan 29, 2026
52076e7
Fine tune test schema trigger
BaptisteGi Jan 29, 2026
65ca106
Checkout with head
BaptisteGi Jan 29, 2026
adf6d09
docs: auto-generate reference [skip ci]
Jan 29, 2026
d495525
Report CI status
BaptisteGi Jan 29, 2026
0c7c76d
Fix mdlint
BaptisteGi Jan 29, 2026
8aa9cef
Just check the documentation no commit
BaptisteGi Feb 6, 2026
0c8898b
Fix
BaptisteGi Feb 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .github/file-filters.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ yaml_all: &yaml_all
markdown_all: &markdown_all
- "**/*.{md,mdx}"

schema_all: &schema_all
- "base/**/*.{yml,yaml}"
- "extensions/**/*.{yml,yaml}"

documentation_all:
- *doc_files
- *markdown_all
53 changes: 43 additions & 10 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
# yamllint disable rule:truthy rule:truthy rule:line-length

name: "CI"
on:
pull_request:
Expand All @@ -24,6 +25,7 @@ jobs:
documentation: ${{ steps.changes.outputs.documentation_all }}
markdown: ${{ steps.changes.outputs.markdown_all }}
python: ${{ steps.changes.outputs.python_all }}
schema: ${{ steps.changes.outputs.schema_all }}
yaml: ${{ steps.changes.outputs.yaml_all }}
steps:
- name: "Check out repository code"
Expand Down Expand Up @@ -111,7 +113,7 @@ jobs:
always() && !cancelled() &&
!contains(needs.*.result, 'failure') &&
!contains(needs.*.result, 'cancelled') &&
needs.files-changed.outputs.yaml == 'true'
needs.files-changed.outputs.schema == 'true'
runs-on:
group: huge-runners
env:
Expand Down Expand Up @@ -150,16 +152,24 @@ jobs:
if: always()
run: uv run invoke destroy

documentation:
check-documentation:
name: Check generated documentation is up to date
defaults:
run:
working-directory: ./docs
if: |
always() && !cancelled() &&
!contains(needs.*.result, 'failure') &&
!contains(needs.*.result, 'cancelled') &&
needs.files-changed.outputs.documentation == 'true'
needs: ["files-changed", "yaml-lint", "python-lint"]
github.event_name == 'pull_request'
needs:
[
"files-changed",
"yaml-lint",
"python-lint",
"markdown-lint",
"schema-test",
]
runs-on: "ubuntu-22.04"
timeout-minutes: 5
steps:
Expand All @@ -171,7 +181,7 @@ jobs:
uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
cache: "npm"
cache-dependency-path: docs/package-lock.json
- name: "Install uv"
uses: "astral-sh/setup-uv@v5"
Expand All @@ -186,24 +196,47 @@ jobs:
- name: "Generate reference documentation"
run: "uv run invoke docs.generate"
working-directory: ./
- name: "Build docs website"
run: "uv run invoke docs.build"
- name: "Check for outdated documentation"
run: |
if ! git diff --exit-code -- docs/reference/; then
echo "::error::Generated documentation is out of date. Please run 'invoke docs.generate' locally and commit the changes."
exit 1
fi
working-directory: ./

validate-documentation-style:
validate-documentation:
if: |
always() && !cancelled() &&
!contains(needs.*.result, 'failure') &&
!contains(needs.*.result, 'cancelled') &&
needs.files-changed.outputs.documentation == 'true'
needs: ["files-changed", "yaml-lint", "python-lint"]
github.event_name == 'pull_request'
needs: ["check-documentation"]
runs-on: "ubuntu-22.04"
timeout-minutes: 5
steps:
- name: "Check out repository code"
uses: "actions/checkout@v4"
with:
submodules: true
- name: Install NodeJS
uses: actions/setup-node@v4
with:
node-version: 20
cache: "npm"
cache-dependency-path: docs/package-lock.json
- name: "Install uv"
uses: "astral-sh/setup-uv@v5"
with:
version: "0.9.18"
- name: "Install Python dependencies"
run: "uv sync"
working-directory: ./
- name: "Install dependencies"
run: "uv run invoke docs.install"
working-directory: ./
- name: "Build docs website"
run: "uv run invoke docs.build"
working-directory: ./
# The official GitHub Action for Vale doesn't work, installing manually instead:
# https://github.com/errata-ai/vale-action/issues/103
- name: Download Vale
Expand Down
37 changes: 24 additions & 13 deletions .markdownlint.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,28 @@
---
# Markdownlint configuration
# https://github.com/DavidAnson/markdownlint

default: true

# MD007/ul-indent - Unordered list indentation
MD007:
indent: 4 # sets indent size to 4 spaces
MD013: false # disables max line-length
MD024: false # disables 'no duplicate headings',
# which we use in tabs for instructions
indent: 4

# MD013/line-length - Line length (disabled for readability in prose)
MD013: false

# MD024/no-duplicate-heading - Multiple headings with the same content
# Allow duplicate headings in different sections
MD024:
siblings_only: true

# MD025/single-title - Multiple top-level headings
# Prevent collisions with h1s and frontmatter titles
MD025:
front_matter_title: "" # prevent collisions with h1s
# and frontmatter titles
MD029: false # allows manually creating ordered lists
MD033: false # allows inline html to override markdown styles
MD034: false # no-bare-urls
MD045: false # no alt text around images
MD047: false # single trailing newline
MD014: false # dollar signs used before commands
MD060: false # table column style - disabled for generated tables
front_matter_title: ""

# MD033/no-inline-html - Inline HTML (disabled for MDX React components)
MD033: false

# MD060/table-column-style - Table column style (disabled for generated tables)
MD060: false
1 change: 1 addition & 0 deletions .markdownlintignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
docs/node_modules/
.venv/
docs/docs/reference
2 changes: 1 addition & 1 deletion docs/docs/home.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,4 +156,4 @@ This error indicates that the schema you are trying to load has dependencies on

To resolve this, ensure that you have loaded all required schemas before attempting to load the one in question. You can find the list of dependencies in the schema documentation.

:::
:::
26 changes: 6 additions & 20 deletions docs/docs/reference/azure.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,6 @@ This schema extension introduces cloud support for Microsoft Azure.
### Location

- **Namespace:** Azure
- **Display Labels:** name__value

#### Attributes

Expand All @@ -26,7 +25,6 @@ This schema extension introduces cloud support for Microsoft Azure.
### Tenant

- **Namespace:** Azure
- **Display Labels:** name__value, tenant_id__value

#### Attributes

Expand All @@ -44,7 +42,6 @@ This schema extension introduces cloud support for Microsoft Azure.
### Subscription

- **Namespace:** Azure
- **Display Labels:** name__value, subscription_id__value

#### Attributes

Expand All @@ -63,7 +60,6 @@ This schema extension introduces cloud support for Microsoft Azure.
### ResourceGroup

- **Namespace:** Azure
- **Display Labels:** name__value

#### Attributes

Expand All @@ -82,7 +78,6 @@ This schema extension introduces cloud support for Microsoft Azure.

- **Label:** Virtual Networks
- **Namespace:** Azure
- **Display Labels:** name__value
- **Inherit From:** AzureResource

#### Relationships
Expand All @@ -96,7 +91,6 @@ This schema extension introduces cloud support for Microsoft Azure.

- **Label:** Subnets
- **Namespace:** Azure
- **Display Labels:** name__value

#### Attributes

Expand Down Expand Up @@ -157,17 +151,14 @@ nodes:
- name: Location
namespace: Azure
menu_placement: AzureResource
display_labels:
- name__value
display_label: name__value
attributes:
- name: name
kind: Text
- name: Tenant
namespace: Azure
menu_placement: AzureResource
display_labels:
- name__value
- tenant_id__value
display_label: '{{ name__value }} (Tenant ID: {{ tenant_id__value }})'
attributes:
- name: name
kind: Text
Expand All @@ -181,9 +172,7 @@ nodes:
- name: Subscription
namespace: Azure
menu_placement: AzureResource
display_labels:
- name__value
- subscription_id__value
display_label: '{{ name__value }} (Subscription ID: {{ subscription_id__value }})'
attributes:
- name: name
kind: Text
Expand All @@ -202,8 +191,7 @@ nodes:
- name: ResourceGroup
namespace: Azure
menu_placement: AzureResource
display_labels:
- name__value
display_label: name__value
attributes:
- name: name
kind: Text
Expand All @@ -221,8 +209,7 @@ nodes:
label: Virtual Networks
namespace: Azure
menu_placement: AzureResource
display_labels:
- name__value
display_label: name__value
inherit_from:
- AzureResource
relationships:
Expand All @@ -239,8 +226,7 @@ nodes:
namespace: Azure
menu_placement: AzureResource
include_in_menu: true
display_labels:
- name__value
display_label: name__value
attributes:
- name: name
kind: Text
Expand Down
8 changes: 2 additions & 6 deletions docs/docs/reference/circuit.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ This schema extension contains Circuits and ways to connect them with your infra
- **Description:** A Circuit represent service operated by a provider.
- **Namespace:** Dcim
- **Icon:** mdi:cable-data
- **Display Labels:** circuit_id__value
- **Human Friendly ID:** circuit_id__value

#### Attributes
Expand All @@ -44,7 +43,6 @@ This schema extension contains Circuits and ways to connect them with your infra
- **Description:** A circuit endpoint, could be a position in a MMR...
- **Namespace:** Dcim
- **Icon:** mdi:ethernet
- **Display Labels:** name__value
- **Uniqueness Constraints:**
- circuit, name__value
- **Human Friendly ID:** circuit__circuit_id__value, name__value
Expand Down Expand Up @@ -103,8 +101,7 @@ nodes:
- circuit_id__value
order_by:
- circuit_id__value
display_labels:
- circuit_id__value
display_label: circuit_id__value
attributes:
- name: circuit_id
kind: Text
Expand Down Expand Up @@ -186,8 +183,7 @@ nodes:
- name__value
order_by:
- name__value
display_labels:
- name__value
display_label: name__value
attributes:
- name: name
kind: Text
Expand Down
4 changes: 1 addition & 3 deletions docs/docs/reference/circuit_service.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,6 @@ For example you have a MPLS network supported by a provider connecting multiple
- **Description:** Represent the boundary of a provider network, the details of which are unknown or unimportant
- **Namespace:** Circuit
- **Icon:** mdi:cloud
- **Display Labels:** name__value
- **Human Friendly ID:** name__value

#### Attributes
Expand Down Expand Up @@ -79,8 +78,7 @@ nodes:
- name__value
order_by:
- name__value
display_labels:
- name__value
display_label: name__value
attributes:
- name: name
kind: Text
Expand Down
4 changes: 1 addition & 3 deletions docs/docs/reference/cluster.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,6 @@ This schema extension contains the foundations to capture clusters. With this on
- **Description:** A cluster of machines hosting services or other machines.
- **Namespace:** Cluster
- **Icon:** mdi:dots-hexagon
- **Display Labels:** name__value
- **Human Friendly ID:** name__value

#### Attributes
Expand Down Expand Up @@ -84,8 +83,7 @@ generics:
- name__value
order_by:
- name__value
display_labels:
- name__value
display_label: name__value
attributes:
- name: name
kind: Text
Expand Down
4 changes: 1 addition & 3 deletions docs/docs/reference/cross_connect.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@ This extension contains schema to capture Cross Connect. You can see it as "a ca
- **Description:** Cross-connect between different endpoints within a datacenter.
- **Namespace:** Dcim
- **Icon:** streamline:arrow-crossover-right-solid
- **Display Labels:** identifier__value
- **Uniqueness Constraints:**
- identifier__value, provider
- **Human Friendly ID:** provider__name__value, identifier__value
Expand Down Expand Up @@ -52,8 +51,7 @@ nodes:
- DcimConnector
order_by:
- provider__name__value
display_labels:
- identifier__value
display_label: '{{ identifier__value }} (Provider: {{ provider__name__value }})'
human_friendly_id:
- provider__name__value
- identifier__value
Expand Down
Loading