Documentation rework (#51)

* Cleanup metadata

* Cleanup tasks

* Generate reference using template

* Add more context to doc

* Reshuffle doc

* Cleanup

* Set the right title

* Set title

* Various fixes

* Various fixes for lint

* Cleanup schemas.start from CI

* Cleanup

* Further cleanup

* Fix path to metadata

* Found why links were broken

* Ignore reference file from vale

* Cleanup

* Cleanup

* Fix issues around vale

* for vale to ignore reference folder

* Create a per page ref doc + many improvements

* Lint on metadata

* Cleanup contributing

* Cleanuo

* Deactivate vale for TOC

* Vale off

* Pin sdk version and further cleanup

* Round 140 of cleanup

* Add link to dependencies

Author: BaptisteGi

.github/workflows/ci.yml

@@ -48,7 +48,6 @@ jobs:
     steps:
       - name: "Check out repository code"
         uses: "actions/checkout@v4"
-
       - name: "Set up Python ${{ matrix.python-version }}"
         uses: "actions/setup-python@v5"
         with:
@@ -66,7 +65,6 @@ jobs:
           poetry env use ${{ matrix.python-version }}
       - name: "Install dependencies"
         run: "poetry install --no-interaction --no-ansi --with dev"
-
       - name: "Linting: ruff check"
         run: "poetry run ruff check ."
       - name: "Linting: ruff format"
@@ -100,7 +98,6 @@ jobs:
       !contains(needs.*.result, 'failure') &&
       !contains(needs.*.result, 'cancelled') &&
       needs.files-changed.outputs.yaml == 'true'
-
     runs-on:
       group: huge-runners
     env:
@@ -110,39 +107,29 @@ jobs:
         uses: actions/checkout@v4
         with:
           submodules: true
-
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-
       - name: Install Invoke
-        run: |
-          pip install toml invoke infrahub-sdk["all"]
-
+        run: poetry install --no-interaction --no-ansi --with dev
       - name: Set job name
         run: echo JOB_NAME="$GITHUB_JOB" >> $GITHUB_ENV
-
       - name: "Set environment variable INFRAHUB_BUILD_NAME"
         run: echo INFRAHUB_BUILD_NAME=infrahub-${{ runner.name }} >> $GITHUB_ENV
-
       - name: Initialize Infrahub
-        run: invoke schemas.start
-
+        run: poetry run invoke start
       - name: Set infrahub address
         run: |
           PORT=$(docker compose -p $INFRAHUB_BUILD_NAME port infrahub-server 8000 | cut -d: -f2)
           echo "INFRAHUB_ADDRESS=http://localhost:${PORT}" >> $GITHUB_ENV
-
       - name: "Store start time"
         run: echo TEST_START_TIME=$(date +%s)000 >> $GITHUB_ENV
-
       - name: Load all schemas files
-        run: invoke schemas.load-all-schemas
-
+        run: poetry run invoke schemas.load-all-schemas
       - name: "Clear docker environment and force vmagent to stop"
         if: always()
-        run: docker compose -p $INFRAHUB_BUILD_NAME down -v --remove-orphans --rmi local
+        run: poetry run invoke destroy
 
   documentation:
     defaults:
@@ -167,15 +154,15 @@ jobs:
           node-version: 20
           cache: 'npm'
           cache-dependency-path: docs/package-lock.json
-      - name: "Install dependencies"
-        run: npm install
       - name: "Setup Python environment"
         run: "pip install invoke toml"
-      - name: "Create schema docs"
-        run: "invoke schemas.build"
+      - name: "Install dependencies"
+        run: "invoke docs.install"
+      - name: "Generate reference documentation"
+        run: "invoke docs.generate"
         working-directory: ./
       - name: "Build docs website"
-        run: "invoke docusaurus.docs"
+        run: "invoke docs.build"
 
   validate-documentation-style:
     if: |
@@ -201,4 +188,4 @@ jobs:
         env:
           VALE_VERSION: ${{ env.VALE_VERSION }}
       - name: "Validate documentation style"
-        run: ./vale --config=.vale.ini --glob='!{docs/docs/schema-library.*}' ./docs/docs $(find ./docs/docs -type f \( -name "*.mdx" -o -name "*.md" \) )
+        run: ./vale --config=.vale.ini $(find ./docs -type f \( -name "*.mdx" -o -name "*.md" \) -not -path "./docs/node_modules/*" -not -path "./docs/docs/reference/*")

.gitignore

@@ -2,3 +2,4 @@
 .envrc
 .env
 test.sh
+__pycache__

.metadata.yml

@@ -2,20 +2,27 @@
 # yamllint disable rule:line-length
 base/dcim:
   description:
-    Basic DCIM schema to capture devices, racks, interfaces, and related information.
+    Basic DCIM schema to capture devices, racks, interfaces, and related
+    information.
   name: DCIM
 base/ipam:
-  description:
-    Basic IPAM schema to capture IP addresses, subnets, and related information.
+  description: Basic IPAM schema to capture IP addresses, subnets, and related information.
   name: IPAM
 base/location:
-  description:
-    Basic Location schema to capture locations, sites, and related information.
+  description: Basic Location schema to capture locations, sites, and related information.
   name: Locations
 base/organization:
   description:
-    Basic Organization schema to capture organizations, vendors, and related information.
+    Basic Organization schema to capture organizations, vendors, and related
+    information.
   name: Organization
+extensions/cable:
+  dependencies:
+    - base
+  description:
+    This schema extension contains a basic Cable model allowing you to
+    connect two endpoints.
+  name: Cable
 experimental/azure:
   attribution: "[Rowan Coleman](https://www.linkedin.com/in/rowan-coleman-6a147156/)"
   dependencies:
@@ -51,18 +58,18 @@ experimental/modules_linecards:
     - extensions/modules
   description:
     This schema extension allows you to capture Linecard related information
-    like the version. You can insert the Linecard into a Dcim Physical Device
-    and leverage the Linecard type model. The Linecard can accept PIC to help
-    configure PORT information like breakout-capabilities and configurations.
+    like the version. You can insert the Linecard into a Dcim Physical Device and
+    leverage the Linecard type model. The Linecard can accept PIC to help configure
+    PORT information like breakout-capabilities and configurations.
   name: Modules Linecards
 experimental/modules_routing_engine:
   dependencies:
     - base
     - extensions/modules
   description:
-    This schema extension allows you to capture Routing Engine related information
-    like the version. You can insert the Routing Engine into a Dcim Physical Device
-    and leverage the Routing Engine type model.
+    This schema extension allows you to capture Routing Engine related
+    information like the version. You can insert the Routing Engine into a Dcim Physical
+    Device and leverage the Routing Engine type model.
   name: Modules Routing Engine
 experimental/qos:
   dependencies:
@@ -96,13 +103,6 @@ experimental/vlan-translation:
     This schema extension is based on Juniper VLAN MAP, and not yet test
     out for other vendors.
   name: VLAN Translation
-extensions/cable:
-  dependencies:
-    - base
-  description:
-    This schema extension contains a basic Cable model allowing you to
-    connect two endpoints.
-  name: Cable
 extensions/circuit:
   dependencies:
     - base
@@ -121,22 +121,6 @@ extensions/cluster:
     With this one in place you can unlock various clusters flavors (hosting cluster
     able to host VMs, firewall clusters built with specific appliances ...)
   name: Cluster
-extensions/lag:
-  dependencies:
-    - base
-  description:
-    This schema extension includes models for Link Aggregation Groups (LAGs),
-    enabling you to link physical interfaces as building blocs of your LAG interface.
-    It can be used in standard networking environments as well as in compute scenarios,
-    such as capturing bond interfaces.
-  name: Lag
-extensions/interface_breakout:
-  dependencies:
-    - base
-  description:
-    This schema extension introduces relationships to support breakout interfaces,
-    enabling you to document the breakout of a physical interface into smaller physical interfaces.
-  name: Interface Breakout
 extensions/compute:
   dependencies:
     - base
@@ -182,6 +166,23 @@ extensions/hosting_cluster:
     A rather generic cluster built with compute units (e.g. servers) and
     able to host VMs.
   name: Hosting Cluster
+extensions/interface_breakout:
+  dependencies:
+    - base
+  description:
+    This schema extension introduces relationships to support breakout
+    interfaces, enabling you to document the breakout of a physical interface into
+    smaller physical interfaces.
+  name: Interface Breakout
+extensions/lag:
+  dependencies:
+    - base
+  description:
+    This schema extension includes models for Link Aggregation Groups (LAGs),
+    enabling you to link physical interfaces as building blocs of your LAG interface.
+    It can be used in standard networking environments as well as in compute scenarios,
+    such as capturing bond interfaces.
+  name: Lag
 extensions/location_minimal:
   dependencies:
     - base
@@ -212,7 +213,8 @@ extensions/peering_ixp:
     - extensions/routing_bgp
     - extensions/routing_bgp_community
   description:
-    This schema extension contains all you need to model anything revolving around internet peering (Exchange points ...)!
+    This schema extension contains all you need to model anything revolving
+    around internet peering (Exchange points ...)!
   name: Peering IXP
 extensions/physical_disk:
   dependencies:
@@ -227,7 +229,8 @@ extensions/qinq:
     - base
     - extensions/vlan
   description:
-    This schema extension brings extensions to VLAN model in order to support QinQ.
+    This schema extension brings extensions to VLAN model in order to support
+    QinQ.
   name: QinQ
 extensions/routing:
   dependencies:
@@ -284,7 +287,9 @@ extensions/routing_pim:
 extensions/routing_policies:
   dependencies:
     - base
-  description: This schema extension contains a generic to create Routing Policies. This Generic can be extend for each Routing Protocols you may want to use.
+  description:
+    This schema extension contains a generic to create Routing Policies.
+    This Generic can be extend for each Routing Protocols you may want to use.
   name: Routing Policies
 extensions/routing_policies_aggregate:
   dependencies:

README.md

@@ -5,6 +5,12 @@ Welcome to the Schema Library for Infrahub! This repository offers a collection
 > [!WARNING]
 > This project is currently a collection of examples intended to serve as inspiration. Please note that it is in an experimental phase and may undergo significant changes.
 
-## Using the schema library
+## Use case
 
-Documentation for using the Schema Library is available in the [Schema Library docs](https://docs.infrahub.app/schema-library) site.
+Infrahub ships without built-in schemas, giving you complete freedom to define your own. However, starting from scratch can be overwhelming, especially when many infrastructures share common models. That's where the [Schema Library](https://github.com/opsmill/schema-library), maintained by OpsMill and the community, comes in.
+
+**The library provides a curated collection of practical, ready-to-use schemas designed to reflect real-world infrastructure needs. Use them out of the box, or treat them as a foundation: copy, adapt, and extend each schema to align precisely with your organization.**
+
+## Getting started
+
+Interested about the project and want to get started? Check out the [Schema Library documentation](https://docs.infrahub.app/schema-library) for more information.