add documentation to site product block

docs/source/glossary.md

 # Glossary of terms
 
 {.glossary}
+BGP
+: Border Gateway Protocol: a path vector routing protocol described in 
+<a href="https://datatracker.ietf.org/doc/html/rfc4271" target="_blank">RFC 4271</a>.
+
 CRUD
 : Create, Read, Update, Delete
 
@@ -26,5 +30,9 @@ LSO
 NET
 : Network Entity Title: used for {term}`IS-IS` routing.
 
+SNMP
+: Simple Network Management Protocol: a protocol that's used for gathering data, widely used for network management and
+monitoring.
+
 WFO
 : <a href="https://workfloworchestrator.org/" target="_blank">Workflow Orchestrator</a>

docs/vale/.vale.ini

@@ -27,6 +27,7 @@ TokenIgnores = ({term}), (:param \S+:), (:type \S+:)
 [*/glossary.md]
 ; Ignore acronyms being undefined in the file that defines all acronyms by definition.
 Microsoft.Acronyms = NO
+Microsoft.Passive = NO
 
 [formats]
 py = md

gso/products/product_blocks/site.py

+"""The product block that describes a site subscription."""
+
 from typing import Optional
 
 from orchestrator.domain.base import ProductBlockModel
@@ -5,6 +7,12 @@ from orchestrator.types import SubscriptionLifecycle, strEnum
 
 
 class SiteTier(strEnum):
+    """The tier of a site, ranging from 1 to 4.
+
+    A lower value generally corresponds to a larger amount of installed equipment, and a higher cardinality of the
+    connectivity to and from a site.
+    """
+
     TIER1 = 1
     TIER2 = 2
     TIER3 = 3
@@ -12,6 +20,8 @@ class SiteTier(strEnum):
 
 
 class SiteBlockInactive(ProductBlockModel, lifecycle=[SubscriptionLifecycle.INITIAL], product_block_name="SiteBlock"):
+    """A site that's currently inactive, see {class}`SiteBlock`."""
+
     site_name: Optional[str] = None
     site_city: Optional[str] = None
     site_country: Optional[str] = None
@@ -24,6 +34,8 @@ class SiteBlockInactive(ProductBlockModel, lifecycle=[SubscriptionLifecycle.INIT
 
 
 class SiteBlockProvisioning(SiteBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
+    """A site that's currently being provisioned, see {class}`SiteBlock`."""
+
     site_name: Optional[str] = None
     site_city: Optional[str] = None
     site_country: Optional[str] = None
@@ -36,12 +48,25 @@ class SiteBlockProvisioning(SiteBlockInactive, lifecycle=[SubscriptionLifecycle.
 
 
 class SiteBlock(SiteBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
+    """A site that's currently available for devices and services to be hosted at."""
+
     site_name: str
+    """The name of the site, that will dictate part of the {term}`FQDN` of devices that are hosted at this site. For
+    example: `device.X.Y.geant.net`, where X denotes the name of the site."""
     site_city: str
+    """The city at which the site is located."""
     site_country: str
+    """The country in which the site is located."""
     site_country_code: str
+    """The code of the corresponding country. This is also used for the {term}`FQDN`, following the example given for
+    the site name, the country code would end up in the Y position."""
     site_latitude: float
+    """The latitude of the site, used for {term}`SNMP` purposes."""
     site_longitude: float
+    """Similar to the latitude, the longitude of a site."""
     site_internal_id: int
+    """The internal ID used within GÉANT to denote a site."""
     site_bgp_community_id: int
+    """The {term}`BGP` community ID of a site, used to advertise routes learned at this site."""
     site_tier: SiteTier
+    """The tier of a site, as described in {class}`SiteTier`."""