Update docstrings in a more product blocks, remove obsolete :class:`` references

gso/auth/oidc.py

@@ -43,7 +43,7 @@ def ensure_openid_config_loaded(func: Callable) -> Callable:
 
 
 class OIDCAuthentication(OIDCAuth):
-    """OIDCUser class extends the ``HTTPBearer`` class to do extra verification.
+    """OIDCUser class extends the `HTTPBearer` class to do extra verification.
 
     The class will act as follows: Validate the Credentials at the AAI proxy by calling the UserInfo endpoint.
     """

gso/cli/imports.py

@@ -64,11 +64,11 @@ class CreatePartner(BaseModel):
 
 
 class SiteImportModel(BaseSiteValidatorModel):
-    """The required input for importing an existing ``gso.products.product_types.site``."""
+    """The required input for importing an existing `gso.products.product_types.site`."""
 
 
 class RouterImportModel(BaseModel):
-    """Required fields for importing an existing ``gso.product.product_types.router``."""
+    """Required fields for importing an existing `gso.product.product_types.router`."""
 
     partner: str
     router_site: str
@@ -82,7 +82,7 @@ class RouterImportModel(BaseModel):
 
 
 class SwitchImportModel(BaseModel):
-    """Required fields for importing an existing ``gso.product.product_types.switch``."""
+    """Required fields for importing an existing `gso.product.product_types.switch`."""
 
     fqdn: str
     ts_port: PortNumber
@@ -92,7 +92,7 @@ class SwitchImportModel(BaseModel):
 
 
 class SuperPopSwitchImportModel(BaseModel):
-    """Required fields for importing an existing ``gso.product.product_types.super_pop_switch``."""
+    """Required fields for importing an existing `gso.product.product_types.super_pop_switch`."""
 
     partner: str
     super_pop_switch_site: str
@@ -102,7 +102,7 @@ class SuperPopSwitchImportModel(BaseModel):
 
 
 class OfficeRouterImportModel(BaseModel):
-    """Required fields for importing an existing ``gso.product.product_types.office_router``."""
+    """Required fields for importing an existing `gso.product.product_types.office_router`."""
 
     partner: str
     office_router_site: str
@@ -113,7 +113,7 @@ class OfficeRouterImportModel(BaseModel):
 
 
 class IptrunkImportModel(BaseModel):
-    """Required fields for importing an existing ``gso.products.product_types.iptrunk``."""
+    """Required fields for importing an existing `gso.products.product_types.iptrunk`."""
 
     partner: str
     gs_id: IMPORTED_GS_ID | None
@@ -178,7 +178,7 @@ class IptrunkImportModel(BaseModel):
 
 
 class OpenGearImportModel(BaseModel):
-    """Required fields for importing an existing ``gso.products.product_types.opengear``."""
+    """Required fields for importing an existing `gso.products.product_types.opengear`."""
 
     partner: str
     opengear_site: str
@@ -189,7 +189,7 @@ class OpenGearImportModel(BaseModel):
 
 
 class EdgePortImportModel(BaseModel):
-    """Required fields for importing an existing ``gso.products.product_types.edge_port``."""
+    """Required fields for importing an existing `gso.products.product_types.edge_port`."""
 
     node: str
     service_type: EdgePortType

gso/products/product_blocks/bgp_session.py

@@ -14,9 +14,13 @@ class IPFamily(strEnum):
     """Possible IP families of a BGP peering."""
 
     V4UNICAST = "ipv4"
+    """Unicast IPv4"""
     V6UNICAST = "ipv6"
+    """Unicast IPv6"""
     V4MULTICAST = "mcast-ipv4"
+    """Multicast IPv4"""
     V6MULTICAST = "mcast-ipv6"
+    """Multicast IPv6"""
 
 
 @strawberry.enum
@@ -24,11 +28,13 @@ class IPTypes(strEnum):
     """Possible IP types of a BGP peering."""
 
     IPV4 = "ipv4"
+    """IPv4"""
     IPV6 = "ipv6"
+    """IPv6"""
 
 
 class BGPSessionInactive(ProductBlockModel, lifecycle=[SubscriptionLifecycle.INITIAL], product_block_name="BGPSession"):
-    """A BGP session that is currently inactive. See ``BGPSession``."""
+    """A BGP session that is currently inactive. See `BGPSession`."""
 
     peer_address: IPAddress | None = None
     families: list[IPFamily] = Field(default_factory=list)
@@ -45,7 +51,7 @@ class BGPSessionInactive(ProductBlockModel, lifecycle=[SubscriptionLifecycle.INI
 
 
 class BGPSessionProvisioning(BGPSessionInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """A BGP session that is currently being provisioned. See ``BGPSession``."""
+    """A BGP session that is currently being provisioned. See `BGPSession`."""
 
     peer_address: IPAddress
     families: list[IPFamily]
@@ -62,29 +68,32 @@ class BGPSessionProvisioning(BGPSessionInactive, lifecycle=[SubscriptionLifecycl
 
 
 class BGPSession(BGPSessionProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
-    """A BGP session that is currently deployed in the network."""
+    """A BGP session that is currently deployed in the network.
+
+    Attributes:
+        peer_address: The peering address of the session.
+        families: The list of IP families enabled for this session.
+        has_custom_policies: Whether any custom policies exist for this session.
+        authentication_key: The authentication key of the BGP session.
+        multipath_enabled: Whether multi-path is enabled.
+        send_default_route: Whether we send a last resort route.
+        is_multi_hop: Whether this session is multi-hop or not. Defaults to no.
+        is_passive: Whether this is a passive session.
+        rtbh_enabled: Whether Remote Triggered Blackhole is enabled.
+        bfd_enabled: Settings for BFD.
+        ip_type: The IP type of the session.
+        prefix_limit: A prefix limit, if required.
+    """
 
-    #: The peering address of the session.
     peer_address: IPAddress
-    #: The list of IP families enabled for this session.
     families: list[IPFamily]
-    #: Whether any custom policies exist for this session.
     has_custom_policies: bool
-    #: The authentication key of the BGP session.
     authentication_key: str | None
-    #: Whether multi-path is enabled.
     multipath_enabled: bool
-    #: Whether we send a last resort route.
     send_default_route: bool
-    #: Whether this session is multi-hop or not. Defaults to no.
     is_multi_hop: bool
-    #: Whether this is a passive session.
     is_passive: bool
-    #: Whether Remote Triggered Blackhole is enabled
     rtbh_enabled: bool
-    #: Settings for BFD.
     bfd_enabled: bool
-    #: The IP type of the session.
     ip_type: IPTypes
-    #: A prefix limit, if required
     prefix_limit: NonNegativeInt | None

gso/products/product_blocks/iptrunk.py

@@ -94,7 +94,7 @@ class IptrunkBlockInactive(
     lifecycle=[SubscriptionLifecycle.INITIAL],
     product_block_name="IptrunkBlock",
 ):
-    """A trunk that's currently inactive, see ``IptrunkBlock``."""
+    """A trunk that's currently inactive, see `IptrunkBlock`."""
 
     gs_id: str | None = None
     iptrunk_description: str | None = None
@@ -108,7 +108,7 @@ class IptrunkBlockInactive(
 
 
 class IptrunkBlockProvisioning(IptrunkBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """A trunk that's currently being provisioned, see ``IptrunkBlock``."""
+    """A trunk that's currently being provisioned, see `IptrunkBlock`."""
 
     gs_id: str | None = None
     iptrunk_description: str | None = None
@@ -122,23 +122,26 @@ class IptrunkBlockProvisioning(IptrunkBlockInactive, lifecycle=[SubscriptionLife
 
 
 class IptrunkBlock(IptrunkBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
-    """A trunk that's currently deployed in the network."""
+    """A trunk that's currently deployed in the network.
+
+    Attributes:
+        gs_id: GÉANT service ID associated with this trunk.
+        iptrunk_description: A human-readable description of this trunk.
+        iptrunk_type: The type of trunk, can be either dark fibre or leased capacity.
+        iptrunk_speed: The speed of the trunk, measured per interface associated with it.
+        iptrunk_minimum_links: The minimum amount of links the trunk should consist of.
+        iptrunk_isis_metric: The ISIS metric of this link.
+        iptrunk_ipv4_network: The IPv4 network used for this trunk.
+        iptrunk_ipv6_network: The IPv6 network used for this trunk.
+        iptrunk_sides: The two sides that the trunk is connected to.
+    """
 
-    #:  GÉANT service ID associated with this trunk.
     gs_id: str | None = None
-    #:  A human-readable description of this trunk.
     iptrunk_description: str | None = None
-    #:  The type of trunk, can be either dark fibre or leased capacity.
     iptrunk_type: IptrunkType
-    #:  The speed of the trunk, measured per interface associated with it.
     iptrunk_speed: PhysicalPortCapacity
-    #:  The minimum amount of links the trunk should consist of.
     iptrunk_minimum_links: int
-    #:  The ISIS metric of this link
     iptrunk_isis_metric: int
-    #:  The IPv4 network used for this trunk.
     iptrunk_ipv4_network: ipaddress.IPv4Network
-    #:  The IPv6 network used for this trunk.
     iptrunk_ipv6_network: ipaddress.IPv6Network
-    #:  The two sides that the trunk is connected to.
     iptrunk_sides: IptrunkSides[IptrunkSideBlock]  # type: ignore[assignment]

gso/products/product_blocks/l3_core_service.py

@@ -33,6 +33,7 @@ class AccessPort(AccessPortProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE
         ap_type: The type of Access Port
         sbp: The corresponding SBP of this Access Port.
     """
+
     ap_type: APType
     sbp: ServiceBindingPort
 
@@ -57,4 +58,5 @@ class L3CoreServiceBlock(L3CoreServiceBlockProvisioning, lifecycle=[Subscription
     Attributes:
         ap_list: The list of Access Points where this service is present.
     """
+
     ap_list: list[AccessPort]  # type: ignore[assignment]

gso/products/product_blocks/layer_2_circuit.py

@@ -95,21 +95,24 @@ class Layer2CircuitBlockProvisioning(Layer2CircuitBlockInactive, lifecycle=[Subs
 
 
 class Layer2CircuitBlock(Layer2CircuitBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
-    """An active Layer 2 Circuit."""
+    """An active Layer 2 Circuit.
+
+    Attributes:
+        layer_2_circuit_sides: The two sides that the Layer 2 Circuit is connected to.
+        virtual_circuit_id: Virtual Circuit ID of this Layer 2 Circuit.
+        layer_2_circuit_type: The type of circuit, can be tagged or untagged.
+        vlan_range_lower_bound: If tagged, the lower and upper bounds will set the VLAN range.
+        vlan_range_upper_bound: Lower and Upper bounds are including.
+        policer_enabled: Whether this Layer 2 Circuit is policed.
+        policer_burst_rate: If policed, the burst rate of the policer.
+        bandwidth: If policed, the bandwidth of the policer is stored.
+    """
 
-    #: The two sides that the Layer 2 Circuit is connected to.
     layer_2_circuit_sides: Layer2CircuitSides[Layer2CircuitSideBlock]
-    #: Virtual Circuit ID of this Layer 2 Circuit.
     virtual_circuit_id: VC_ID
-    #: The type of circuit, can be tagged or untagged.
     layer_2_circuit_type: Layer2CircuitType
-    #: If tagged, the lower and upper bounds will set the VLAN range.
     vlan_range_lower_bound: VLAN_ID | None
-    #: Lower and Upper bounds are including.
     vlan_range_upper_bound: VLAN_ID | None
-    #: Whether this Layer 2 Circuit is policed.
     policer_enabled: bool
-    #: If policed, the burst rate of the policer
     policer_burst_rate: BandwidthString | None
-    #: If policed, the bandwidth of the policer is stored.
     bandwidth: BandwidthString | None

gso/products/product_blocks/office_router.py

@@ -17,39 +17,43 @@ class OfficeRouterBlockInactive(
     lifecycle=[SubscriptionLifecycle.INITIAL],
     product_block_name="OfficeRouterBlock",
 ):
-    """An office router that's being currently inactive. See ``OfficeRouterBlock``."""
+    """An office router that's being currently inactive. See `OfficeRouterBlock`."""
 
     office_router_fqdn: str | None = None
     office_router_ts_port: PortNumber | None = None
     office_router_lo_ipv4_address: IPv4AddressType | None = None
     office_router_lo_ipv6_address: IPv6AddressType | None = None
     office_router_site: SiteBlockInactive | None
-    vendor: Vendor | None = None
+    vendor: Vendor | None = Vendor.JUNIPER
 
 
 class OfficeRouterBlockProvisioning(OfficeRouterBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """An office router that's being provisioned. See ``RouterBlock``."""
+    """An office router that's being provisioned. See `RouterBlock`."""
 
-    office_router_fqdn: str | None = None
-    office_router_ts_port: PortNumber | None = None
-    office_router_lo_ipv4_address: IPv4AddressType | None = None
-    office_router_lo_ipv6_address: IPv6AddressType | None = None
+    office_router_fqdn: str | None
+    office_router_ts_port: PortNumber | None
+    office_router_lo_ipv4_address: IPv4AddressType | None
+    office_router_lo_ipv6_address: IPv6AddressType | None
     office_router_site: SiteBlockProvisioning | None
-    vendor: Vendor | None = None
+    vendor: Vendor
 
 
 class OfficeRouterBlock(OfficeRouterBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
-    """An office router that's currently deployed in the network."""
+    """An office router that's currently deployed in the network.
+
+    Attributes:
+        office_router_fqdn: Office router FQDN.
+        office_router_ts_port: The port of the terminal server that this office router is connected to. Used to offer
+            out of band access.
+        office_router_lo_ipv4_address: The IPv4 loopback address of the office router.
+        office_router_lo_ipv6_address: The IPv6 loopback address of the office router.
+        office_router_site: The `Site` that this office router resides in. Both physically and computationally.
+        vendor: The vendor of an office router. Defaults to Juniper.
+    """
 
-    #:  Office router FQDN.
     office_router_fqdn: str
-    #:  The port of the terminal server that this office router is connected to. Used to offer out of band access.
     office_router_ts_port: PortNumber
-    #:  The IPv4 loopback address of the office router.
     office_router_lo_ipv4_address: IPv4AddressType
-    #:  The IPv6 loopback address of the office router.
     office_router_lo_ipv6_address: IPv6AddressType
-    #:  The ``Site`` that this office router resides in. Both physically and computationally.
     office_router_site: SiteBlock
-    #:  The vendor of an office router. Defaults to Juniper.
-    vendor: Vendor = Vendor.JUNIPER
+    vendor: Vendor

gso/products/product_blocks/opengear.py

-"""Product block for ``Opengear`` products."""
+"""Product block for `Opengear` products."""
 
 import ipaddress
 
@@ -17,7 +17,7 @@ class OpengearBlockInactive(
     lifecycle=[SubscriptionLifecycle.INITIAL],
     product_block_name="OpengearBlock",
 ):
-    """An Opengear that's being currently inactive. See ``OpengearBlock``."""
+    """An Opengear that's being currently inactive. See `OpengearBlock`."""
 
     opengear_hostname: str | None = None
     opengear_site: SiteBlockInactive | None = None
@@ -27,7 +27,7 @@ class OpengearBlockInactive(
 
 
 class OpengearBlockProvisioning(OpengearBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """An Opengear that's being provisioned. See ``OpengearBlock``."""
+    """An Opengear that's being provisioned. See `OpengearBlock`."""
 
     opengear_hostname: str
     opengear_site: SiteBlockProvisioning

gso/products/product_blocks/pop_vlan.py

@@ -60,7 +60,7 @@ class PopVlanBlockInactive(
     lifecycle=[SubscriptionLifecycle.INITIAL],
     product_block_name="PopVlanBlock",
 ):
-    """A PoP VLAN that's currently inactive, see ``PopVlanBlock``."""
+    """A PoP VLAN that's currently inactive, see `PopVlanBlock`."""
 
     vlan_id: int
     pop_vlan_description: str | None = None
@@ -72,7 +72,7 @@ class PopVlanBlockInactive(
 
 
 class PopVlanBlockProvisioning(PopVlanBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """A Pop VLAN that's currently being provisioned, see ``PopVlanBlock``."""
+    """A Pop VLAN that's currently being provisioned, see `PopVlanBlock`."""
 
     vlan_id: int
     pop_vlan_description: str | None

gso/products/product_blocks/router.py

-"""Product block for ``Router`` products."""
+"""Product block for `Router` products."""
 
 from orchestrator.domain.base import ProductBlockModel
 from orchestrator.types import SubscriptionLifecycle, strEnum
@@ -25,7 +25,7 @@ class RouterBlockInactive(
     lifecycle=[SubscriptionLifecycle.INITIAL],
     product_block_name="RouterBlock",
 ):
-    """A router that's being currently inactive. See ``RouterBlock``."""
+    """A router that's being currently inactive. See `RouterBlock`."""
 
     router_fqdn: str | None = None
     router_ts_port: PortNumber | None = None
@@ -39,7 +39,7 @@ class RouterBlockInactive(
 
 
 class RouterBlockProvisioning(RouterBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """A router that's being provisioned. See ``RouterBlock``."""
+    """A router that's being provisioned. See `RouterBlock`."""
 
     router_fqdn: str
     router_ts_port: PortNumber
@@ -53,23 +53,28 @@ class RouterBlockProvisioning(RouterBlockInactive, lifecycle=[SubscriptionLifecy
 
 
 class RouterBlock(RouterBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
-    """A router that's currently deployed in the network."""
+    """A router that's currently deployed in the network.
+
+    Attributes:
+        router_fqdn: FQDN of a router.
+        router_ts_port: The port of the terminal server that this router is connected to. Used to offer out of band
+            access.
+        router_access_via_ts: Whether this router should be accessed through the terminal server, or through its
+            loopback address.
+        router_lo_ipv4_address: The IPv4 loopback address of the router.
+        router_lo_ipv6_address: The IPv6 loopback address of the router.
+        router_lo_iso_address: The ISO NET of the router, used for ISIS support.
+        router_role: The role of the router, which can be any of the values defined in `RouterRole`.
+        router_site: The site that this router resides in. Both physically and computationally.
+        vendor: The vendor of a router.
+    """
 
-    #:  FQDN of a router.
     router_fqdn: str
-    #:  The port of the terminal server that this router is connected to. Used to offer out of band access.
     router_ts_port: PortNumber
-    #:  Whether this router should be accessed through the terminal server, or through its loopback address.
     router_access_via_ts: bool
-    #:  The IPv4 loopback address of the router.
     router_lo_ipv4_address: IPv4AddressType
-    #:  The IPv6 loopback address of the router.
     router_lo_ipv6_address: IPv6AddressType
-    #:  The ISO NET of the router, used for ISIS support.
     router_lo_iso_address: str
-    #:  The role of the router, which can be any of the values defined in ``RouterRole``.
     router_role: RouterRole
-    #:  The ``Site`` that this router resides in. Both physically and computationally.
     router_site: SiteBlock
-    #:  The vendor of a router.
     vendor: Vendor

gso/products/product_blocks/service_binding_port.py

@@ -21,7 +21,7 @@ from gso.utils.types.virtual_identifiers import VLAN_ID
 class BFDSettingsInactive(
     ProductBlockModel, lifecycle=[SubscriptionLifecycle.INITIAL], product_block_name="BFDSettings"
 ):
-    """Settings for BFD, see ``BFDSettings``."""
+    """Settings for BFD, see `BFDSettings`."""
 
     bfd_enabled: bool = False
     bfd_interval_rx: int | None = None
@@ -30,7 +30,7 @@ class BFDSettingsInactive(
 
 
 class BFDSettingsProvisioning(BFDSettingsInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """Settings for BFD, see ``BFDSettings``."""
+    """Settings for BFD, see `BFDSettings`."""
 
     bfd_enabled: bool
     bfd_interval_rx: int | None = None
@@ -47,6 +47,7 @@ class BFDSettings(BFDSettingsProvisioning, lifecycle=[SubscriptionLifecycle.ACTI
         bfd_interval_tx: The BFD interval TX, if enabled.
         bfd_multiplier: The BFD multiplier, if enabled.
     """
+
     bfd_enabled: bool
     bfd_interval_rx: int | None
     bfd_interval_tx: int | None
@@ -56,7 +57,7 @@ class BFDSettings(BFDSettingsProvisioning, lifecycle=[SubscriptionLifecycle.ACTI
 class ServiceBindingPortInactive(
     ProductBlockModel, lifecycle=[SubscriptionLifecycle.INITIAL], product_block_name="ServiceBindingPort"
 ):
-    """A Service Binding Port that's currently inactive. See ``ServiceBindingPort``."""
+    """A Service Binding Port that's currently inactive. See `ServiceBindingPort`."""
 
     is_tagged: bool | None = None
     vlan_id: VLAN_ID | None = None
@@ -74,7 +75,7 @@ class ServiceBindingPortInactive(
 
 
 class ServiceBindingPortProvisioning(ServiceBindingPortInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """A Service Binding Port that's currently being provisioned. See ``ServiceBindingPort``."""
+    """A Service Binding Port that's currently being provisioned. See `ServiceBindingPort`."""
 
     is_tagged: bool
     vlan_id: VLAN_ID | None = None
@@ -92,31 +93,34 @@ class ServiceBindingPortProvisioning(ServiceBindingPortInactive, lifecycle=[Subs
 
 
 class ServiceBindingPort(ServiceBindingPortProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
-    """A service binding port that is actively used in the network."""
+    """A service binding port that is actively used in the network.
+
+    Attributes:
+        is_tagged: Whether this VLAN is tagged or not.
+        vlan_id: The VLAN ID.
+        sbp_type: Is this service binding port layer 2 or 3?
+        ipv4_address: If layer 3, IPv4 resources.
+        ipv4_mask: IPv4 subnet mask.
+        ipv6_address: If layer 3, IPv6 resources.
+        ipv6_mask: IPv6 subnet mask.
+        custom_firewall_filters: Any custom firewall filters that the partner may require.
+        gs_id: The GÉANT service ID of this binding port.
+        bgp_session_list: The BGP sessions associated with this service binding port.
+        edge_port: The Edge Port on which this SBP resides.
+        v4_bfd_settings: BFD settings for IPv4.
+        v6_bfd_settings: BFD settings for IPv6.
+    """
 
-    #: Whether this VLAN is tagged or not.
     is_tagged: bool
-    #: The VLAN ID.
     vlan_id: VLAN_ID | None = None
-    #: Is this service binding port layer 2 or 3?
     sbp_type: SBPType
-    #: If layer 3, IPv4 resources.
     ipv4_address: IPv4AddressType | None = None
-    #: IPV4 subnet mask.
     ipv4_mask: IPv4Netmask | None = None
-    #: If layer 3, IPv6 resources.
     ipv6_address: IPv6AddressType | None = None
-    #: IPV6 subnet mask.
     ipv6_mask: IPv6Netmask | None = None
-    #: Any custom firewall filters that the partner may require.
     custom_firewall_filters: bool
-    #: The GÉANT service ID of this binding port.
     gs_id: str
-    #: The BGP sessions associated with this service binding port.
     bgp_session_list: list[BGPSession]  # type: ignore[assignment]
-    #: The Edge Port on which this SBP resides.
     edge_port: EdgePortBlock
-    #: BFD settings for IPv4
     v4_bfd_settings: BFDSettings
-    #: BFD settings for IPv6
     v6_bfd_settings: BFDSettings

gso/products/product_blocks/site.py

@@ -26,7 +26,7 @@ class SiteBlockInactive(
     lifecycle=[SubscriptionLifecycle.INITIAL],
     product_block_name="SiteBlock",
 ):
-    """A site that's currently inactive, see ``SiteBlock``."""
+    """A site that's currently inactive, see `SiteBlock`."""
 
     site_name: SiteName | None = None
     site_city: str | None = None
@@ -42,7 +42,7 @@ class SiteBlockInactive(
 
 
 class SiteBlockProvisioning(SiteBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """A site that's currently being provisioned, see ``SiteBlock``."""
+    """A site that's currently being provisioned, see `SiteBlock`."""
 
     site_name: SiteName
     site_city: str
@@ -61,7 +61,7 @@ class SiteBlock(SiteBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE])
     """A site that's currently available for routers and services to be hosted at."""
 
     #:  The name of the site, that will dictate part of the FQDN of routers that are hosted at this site. For
-    #:  example: ``router.X.Y.geant.net``, where X denotes the name of the site.
+    #:  example: `router.X.Y.geant.net`, where X denotes the name of the site.
     site_name: SiteName
     #:  The city at which the site is located.
     site_city: str
@@ -78,7 +78,7 @@ class SiteBlock(SiteBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE])
     site_internal_id: int
     #:  The BGP community ID of a site, used to advertise routes learned at this site.
     site_bgp_community_id: int
-    #:  The tier of a site, as described in ``SiteTier``.
+    #:  The tier of a site, as described in `SiteTier`.
     site_tier: SiteTier
     #:  The address of the terminal server that this router is connected to. The terminal server provides out of band
     #:  access. This is required in case a link goes down, or when a router is initially added to the network and it

gso/products/product_blocks/super_pop_switch.py

@@ -17,7 +17,7 @@ class SuperPopSwitchBlockInactive(
     lifecycle=[SubscriptionLifecycle.INITIAL],
     product_block_name="SuperPopSwitchBlock",
 ):
-    """A Super PoP switch that's being currently inactive. See ``SuperPoPSwitchBlock``."""
+    """A Super PoP switch that's being currently inactive. See `SuperPoPSwitchBlock`."""
 
     super_pop_switch_fqdn: str | None = None
     super_pop_switch_ts_port: PortNumber | None = None
@@ -27,7 +27,7 @@ class SuperPopSwitchBlockInactive(
 
 
 class SuperPopSwitchBlockProvisioning(SuperPopSwitchBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """A Super PoP switch that's being provisioned. See ``SuperPoPSwitchBlock``."""
+    """A Super PoP switch that's being provisioned. See `SuperPoPSwitchBlock`."""
 
     super_pop_switch_fqdn: str | None = None
     super_pop_switch_ts_port: PortNumber | None = None
@@ -45,7 +45,7 @@ class SuperPopSwitchBlock(SuperPopSwitchBlockProvisioning, lifecycle=[Subscripti
     super_pop_switch_ts_port: PortNumber
     #:  The IPv4 management address of the Super PoP switch.
     super_pop_switch_mgmt_ipv4_address: IPv4AddressType
-    #:  The ``Site`` that this Super PoP switch resides in. Both physically and computationally.
+    #:  The `Site` that this Super PoP switch resides in. Both physically and computationally.
     super_pop_switch_site: SiteBlock
     #:  The vendor of a Super PoP switch. Defaults to Juniper.
     vendor: Vendor = Vendor.JUNIPER

gso/products/product_blocks/switch.py

-"""Product block for ``Switch`` products."""
+"""Product block for `Switch` products."""
 
 from orchestrator.domain.base import ProductBlockModel
 from orchestrator.types import SubscriptionLifecycle
@@ -26,7 +26,7 @@ class SwitchBlockInactive(
     lifecycle=[SubscriptionLifecycle.INITIAL],
     product_block_name="SwitchBlock",
 ):
-    """A switch that's being currently inactive. See ``SwitchBlock``."""
+    """A switch that's being currently inactive. See `SwitchBlock`."""
 
     fqdn: str | None = None
     ts_port: PortNumber | None = None
@@ -36,7 +36,7 @@ class SwitchBlockInactive(
 
 
 class SwitchBlockProvisioning(SwitchBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """A switch that's being provisioned. See ``SwitchBlock``."""
+    """A switch that's being provisioned. See `SwitchBlock`."""
 
     fqdn: str
     ts_port: PortNumber
@@ -46,15 +46,18 @@ class SwitchBlockProvisioning(SwitchBlockInactive, lifecycle=[SubscriptionLifecy
 
 
 class SwitchBlock(SwitchBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
-    """A switch that's currently deployed in the network."""
+    """A switch that's currently deployed in the network.
+
+    Attributes:
+        fqdn: The FQDN of the switch.
+        ts_port: The port of the terminal server that this switch is connected to. Used to offer out of band access.
+        site: The site that this switch resides in. Both physically and computationally.
+        switch_vendor: The vendor of the switch.
+        switch_model: The model of the switch.
+    """
 
-    #: The FQDN of the switch.
     fqdn: str
-    #:  The port of the terminal server that this switch is connected to. Used to offer out of band access.
     ts_port: PortNumber
-    #:  The ``Site`` that this switch resides in. Both physically and computationally.
     site: SiteBlock
-    #: The vendor of the switch.
     switch_vendor: Vendor
-    #: The model of the switch.
     switch_model: SwitchModel

gso/products/product_blocks/vrf.py

-"""Product blocks for :term:`VRF` Virtual Routing and Forwarding."""
+"""Product blocks for VRF Virtual Routing and Forwarding."""
 
 from orchestrator.domain.base import ProductBlockModel
 from orchestrator.types import SubscriptionLifecycle
@@ -7,7 +7,7 @@ from gso.products.product_blocks.router import RouterBlock, RouterBlockInactive,
 
 
 class VRFBlockInactive(ProductBlockModel, lifecycle=[SubscriptionLifecycle.INITIAL], product_block_name="VRFBlock"):
-    """An inactive :term:`VRF` subscription. See :class:`VRFBlock`."""
+    """An inactive VRF subscription. See `VRFBlock`."""
 
     vrf_router_list: list[RouterBlockInactive]
     vrf_name: str | None = None
@@ -17,7 +17,7 @@ class VRFBlockInactive(ProductBlockModel, lifecycle=[SubscriptionLifecycle.INITI
 
 
 class VRFBlockProvisioning(VRFBlockInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """A provisioning :term:`VRF` subscription. See :class:`VRFBlock`."""
+    """A provisioning VRF subscription. See `VRFBlock`."""
 
     vrf_router_list: list[RouterBlockProvisioning]  # type: ignore[assignment]
     vrf_name: str
@@ -27,15 +27,18 @@ class VRFBlockProvisioning(VRFBlockInactive, lifecycle=[SubscriptionLifecycle.PR
 
 
 class VRFBlock(VRFBlockProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
-    """Represents an active :term:`VRF` subscription block."""
+    """Represents an active VRF subscription block.
+
+    Attributes:
+        vrf_router_list: List of VRF routers.
+        vrf_name: Unique name identifying this VRF.
+        route_distinguisher: Route Distinguisher ensuring unique route identification within this VRF.
+        route_target: Route Target defining routing policies for importing/exporting routes.
+        vrf_as_number: AS number of the VRF.
+    """
 
-    #: List of VRF routers
     vrf_router_list: list[RouterBlock]  # type: ignore[assignment]
-    #: Unique name identifying this VRF.
     vrf_name: str
-    #: Route Distinguisher (RD) ensuring unique route identification within this VRF.
     route_distinguisher: str
-    #: Route Target (RT) defining routing policies for importing/exporting routes.
     route_target: str
-    #: AS number of the VRF
     vrf_as_number: int | None = None

gso/products/product_types/vrf.py

-"""A :term:`VRF` product type."""
+"""A VRF product type."""
 
 from orchestrator.domain.base import SubscriptionModel
 from orchestrator.types import SubscriptionLifecycle
@@ -7,18 +7,18 @@ from gso.products.product_blocks.vrf import VRFBlock, VRFBlockInactive, VRFBlock
 
 
 class VRFInactive(SubscriptionModel, is_base=True):
-    """An inactive :term:`VRF`."""
+    """An inactive VRF."""
 
     vrf: VRFBlockInactive
 
 
 class VRFProvisioning(VRFInactive, lifecycle=[SubscriptionLifecycle.PROVISIONING]):
-    """A provisioning :term:`VRF`."""
+    """A provisioning VRF."""
 
     vrf: VRFBlockProvisioning
 
 
 class VRF(VRFProvisioning, lifecycle=[SubscriptionLifecycle.ACTIVE]):
-    """A :term:`VRF` that is currently active."""
+    """A VRF that is currently active."""
 
     vrf: VRFBlock

gso/schedules/scheduling.py

@@ -25,11 +25,11 @@ def scheduler(cron_scheduler_config: CronScheduleConfig) -> Callable[[Callable],
     """Schedule a Celery task using crontab-like timing.
 
     Examples:
-        - ``minute='*/15'``: Run every 15 minutes.
-        - ``hour='*/3'``: Run every 3 hours.
-        - ``day_of_week='mon-fri'``: Run on weekdays only.
-        - ``day_of_month='1-7,15-21'``: Run on the first and third weeks of the month.
-        - ``month_of_year='*/3'``: Run on the first month of each quarter.
+        - `minute='*/15'`: Run every 15 minutes.
+        - `hour='*/3'`: Run every 3 hours.
+        - `day_of_week='mon-fri'`: Run on weekdays only.
+        - `day_of_month='1-7,15-21'`: Run on the first and third weeks of the month.
+        - `month_of_year='*/3'`: Run on the first month of each quarter.
 
     All time units can be specified with lists of numbers or crontab pattern strings for advanced scheduling.
     All specified time parts (minute, hour, day, etc.) must align for a task to run.

gso/services/kentik_client.py

@@ -62,7 +62,7 @@ class KentikClient:
         """List all devices in Kentik.
 
         Returns:
-        a list of shape ``[{**device_1}, {**device_2}, ..., {**device_n}]}``.
+        a list of shape `[{**device_1}, {**device_2}, ..., {**device_n}]}`.
         """
         return self._send_request("GET", "v5/devices")["devices"]
 
@@ -117,7 +117,7 @@ class KentikClient:
         """Get all Kentik plans available.
 
         Returns:
-            a list of ``plans`` that each have the following shape:
+            a list of `plans` that each have the following shape:
 
             .. vale off
             .. code-block:: json

gso/services/lso_client.py

@@ -93,7 +93,7 @@ def _execute_playbook(
 
     .. warning::
        Note the fact that the collection of all hosts is a dictionary, and not a list of strings. Ansible expects each
-       host to be a key-value pair. The key is the FQDN of a host, and the value always ``null``.
+       host to be a key-value pair. The key is the FQDN of a host, and the value always `null`.
 
     The extra vars can be a simple dict consisting of key-value pairs, for example:
 
@@ -196,7 +196,7 @@ def lso_interaction(provisioning_step: Step) -> StepList:
     to provision service subscriptions. If the playbook fails, this step will also fail, allowing for the user to retry
     provisioning from the UI.
 
-    Optionally, the keys ``lso_result_title`` and ``lso_result_extra_label`` can be added to the state before running
+    Optionally, the keys `lso_result_title` and `lso_result_extra_label` can be added to the state before running
     this interaction. They will be used to customise the input step that shows the outcome of the LSO
     interaction.
 
@@ -224,8 +224,8 @@ def lso_interaction(provisioning_step: Step) -> StepList:
 def indifferent_lso_interaction(provisioning_step: Step) -> StepList:
     """Interact with the provisioning proxy LSO using a callback step.
 
-    This interaction is identical from the one described in ``lso_interaction()``, with one functional difference.
-    Whereas the ``lso_interaction()`` will make the workflow step fail on unsuccessful interaction, this step will not.
+    This interaction is identical from the one described in `lso_interaction()`, with one functional difference.
+    Whereas the `lso_interaction()` will make the workflow step fail on unsuccessful interaction, this step will not.
     It is therefore indifferent about the outcome of the Ansible playbook that is executed.
 
     .. warning::
@@ -258,7 +258,7 @@ def anonymous_lso_interaction(provisioning_step: Step, validation_step: Step = _
 
     Similar to the indifferent LSO interaction, there also is the anonymous interaction. Output is not ignored
     but no input step is created to display the results.
-    A custom validation step may be given as input. This validation step should look inside the ``callback_result`` key
+    A custom validation step may be given as input. This validation step should look inside the `callback_result` key
     in the current state. By default, only the return code of the playbook execution is evaluated.
 
     Args:

gso/services/subscriptions.py

@@ -45,7 +45,7 @@ def get_subscriptions(
         partner_id: The customer id of subscriptions.
 
     Returns:
-        A list of ``SubscriptionType`` objects that match the query.
+        A list of `SubscriptionType` objects that match the query.
     """
     if not includes:
         includes = [col.name for col in SubscriptionTable.__table__.columns]
@@ -161,9 +161,9 @@ def get_non_terminated_iptrunk_subscriptions(includes: list[str] | None = None)
 def get_trunks_that_terminate_on_router(
     subscription_id: UUIDstr, lifecycle_state: SubscriptionLifecycle
 ) -> list[SubscriptionTable]:
-    """Get all IP trunk subscriptions that terminate on the given ``subscription_id`` of a Router.
+    """Get all IP trunk subscriptions that terminate on the given `subscription_id` of a Router.
 
-    Given a ``subscription_id`` of a Router subscription, this method gives a list of all IP trunk subscriptions that
+    Given a `subscription_id` of a Router subscription, this method gives a list of all IP trunk subscriptions that
     terminate on this Router. The given lifecycle state dictates the state of trunk subscriptions that are counted as
     terminating on this router.