Fix links and doc style headings (#737)

Signed-off-by: Elliot Gunton <[email protected]>

src/hera/workflows/container_set.py

@@ -29,8 +29,7 @@ class ContainerNode(ContainerMixin, VolumeMountMixin, ResourceMixin, EnvMixin, S
     """A regular container that can be used as part of a `hera.workflows.ContainerSet`.
 
     See Also:
-    --------
-    https://argoproj.github.io/argo-workflows/container-set-template/
+        [Container Set Template](https://argoproj.github.io/argo-workflows/container-set-template/)
     """
 
     name: str

src/hera/workflows/cron_workflow.py

@@ -65,9 +65,10 @@ def build_model(
 class CronWorkflow(Workflow):
     """CronWorkflow allows a user to run a Workflow on a recurring basis.
 
-    NB: Hera's CronWorkflow is a subclass of Workflow which means certain fields are renamed
-    for compatibility, see `cron_suspend` and `cron_status` which are different from the Argo
-    spec. See https://argoproj.github.io/argo-workflows/fields/#cronworkflow
+    Note:
+        Hera's CronWorkflow is a subclass of Workflow which means certain fields are renamed
+        for compatibility, see `cron_suspend` and `cron_status` which are different from the Argo
+        spec. See [CronWorkflowSpec](https://argoproj.github.io/argo-workflows/fields/#cronworkflow) for more details.
     """
 
     concurrency_policy: Annotated[Optional[str], _CronWorkflowModelMapper("spec.concurrency_policy")] = None
@@ -194,7 +195,7 @@ def from_yaml(cls, yaml_str: str) -> ModelMapperMixin:
         """Create a CronWorkflow from a CronWorkflow contained in a YAML string.
 
         Usage:
-            my_cron_workflow = CronWorkflow.from_yaml(yaml_str)
+            >>> my_cron_workflow = CronWorkflow.from_yaml(yaml_str)
         """
         return cls._from_yaml(yaml_str, _ModelCronWorkflow)
 
@@ -203,8 +204,8 @@ def from_file(cls, yaml_file: Union[Path, str]) -> ModelMapperMixin:
         """Create a CronWorkflow from a CronWorkflow contained in a YAML file.
 
         Usage:
-            yaml_file = Path(...)
-            my_workflow_template = CronWorkflow.from_file(yaml_file)
+            >>> yaml_file = Path(...)
+            >>> my_workflow_template = CronWorkflow.from_file(yaml_file)
         """
         return cls._from_file(yaml_file, _ModelCronWorkflow)
 

src/hera/workflows/metrics.py

@@ -37,8 +37,7 @@ class Counter(_BaseMetric):
     """Counter metric component used to count specific events based on the given value.
 
     Notes:
-    -----
-    See: https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics
+        See [https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics](https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics)
     """
 
     value: str
@@ -59,8 +58,7 @@ class Gauge(_BaseMetric, _ModelGauge):
     """Gauge metric component used to record intervals based on the given value.
 
     Notes:
-    -----
-    See: https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics
+        See [https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics](https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics)
     """
 
     realtime: bool
@@ -82,8 +80,7 @@ class Histogram(_BaseMetric):
     """Histogram metric that records the value at the specified bucket intervals.
 
     Notes:
-    -----
-    See: https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics
+        See [https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics](https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics)
     """
 
     buckets: List[Union[float, _ModelAmount]]  # type: ignore
@@ -111,8 +108,7 @@ class Metric(_BaseMetric):
     """Prometheus metric that can be used at the workflow or task/template level.
 
     Notes:
-    -----
-    See: https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics
+        See [https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics](https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics)
     """
 
     counter: Optional[Counter] = None
@@ -140,8 +136,7 @@ class Metrics(BaseMixin):
     """A collection of Prometheus metrics.
 
     Notes:
-    -----
-    See: https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics
+        See [https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics](https://argoproj.github.io/argo-workflows/metrics/#grafana-dashboard-for-argo-controller-metrics)
     """
 
     metrics: List[Metric]

src/hera/workflows/resources.py

@@ -30,34 +30,23 @@ class Resources(_BaseModel):
 
     This follow the K8S definition for resources.
 
-    Parameters
-    ----------
-    cpu_request: Optional[Union[float, int, str]] = None
-        The number of CPUs to request, either as a fraction (millicpu), whole number, or a string.
-    cpu_limit: Optional[Union[int, str]] = None
-        The limit of CPUs to request, either as a fraction (millicpu), whole number, or a string.
-    memory_request: Optional[str] = None
-        The amount of memory to request.
-    memory_limit: Optional[str] = None
-        The memory limit of the pod.
-    ephemeral_request: Optional[str] = None
-        The amount of ephemeral storage to request.
-    ephemeral_limit: Optional[str] = None
-        The ephemeral storage limit of the pod.
-    gpus: Optional[Union[int, str]] = None
-        The number of GPUs to request.
-    gpu_flag: Optional[str] = "nvidia.com/gpu"
-        The GPU flag to use for identifying how many GPUs to mount to a pod. This is dependent on the cloud provider.
-    custom_resources: Optional[Dict] = None
-        Any custom resources to request. This is dependent on the cloud provider.
+    Attributes:
+        cpu_request: The number of CPUs to request, either as a fraction (millicpu), whole number, or a string.
+        cpu_limit: The limit of CPUs to request, either as a fraction (millicpu), whole number, or a string.
+        memory_request: The amount of memory to request.
+        memory_limit: The memory limit of the pod.
+        ephemeral_request: The amount of ephemeral storage to request.
+        ephemeral_limit: The ephemeral storage limit of the pod.
+        gpus: The number of GPUs to request.
+        gpu_flag: The GPU flag to use for identifying how many GPUs to mount to a pod. This is dependent on the cloud provider.
+        custom_resources: Any custom resources to request. This is dependent on the cloud provider.
 
     Notes:
-    -----
-    Most of the fields that support a union of `int` and `str` support either specifying a number for the resource,
-    such as 1 CPU, 2 GPU, etc., a `str` representation of that numerical resource, such as '1' CPU, '2' GPU, etc., but
-    also supports specifying a *to be computed* value, such as `{{inputs.parameters.cpu_request}}`. This means tasks,
-    steps, etc., can be stitched together in a way to have a task/step that *computes* the resource requirements, and
-    then `outputs` them to the next step/task.
+        Most of the fields that support a union of `int` and `str` support either specifying a number for the resource,
+        such as 1 CPU, 2 GPU, etc., a `str` representation of that numerical resource, such as '1' CPU, '2' GPU, etc., but
+        also supports specifying a *to be computed* value, such as `{{inputs.parameters.cpu_request}}`. This means tasks,
+        steps, etc., can be stitched together in a way to have a task/step that *computes* the resource requirements, and
+        then `outputs` them to the next step/task.
     """
 
     cpu_request: Optional[Union[float, int, str]] = None

src/hera/workflows/task.py

@@ -29,7 +29,7 @@ class TaskResult(Enum):
     """The enumeration of Task Results.
 
     See Also:
-        https://argoproj.github.io/argo-workflows/enhanced-depends-logic/#depends.
+        [Argo Depends Docs](https://argoproj.github.io/argo-workflows/enhanced-depends-logic/#depends)
     """
 
     failed = "Failed"

src/hera/workflows/volume.py

@@ -49,8 +49,8 @@ class AccessMode(Enum):
     """A representations of the volume access modes for Kubernetes.
 
     Notes:
-    -----
-    See: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes for more information.
+        See: [access modes docs](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes) for
+        more information.
     """
 
     read_write_once = "ReadWriteOnce"

src/hera/workflows/workflow.py

@@ -476,7 +476,7 @@ def from_yaml(cls, yaml_str: str) -> ModelMapperMixin:
         """Create a Workflow from a Workflow contained in a YAML string.
 
         Usage:
-            my_workflow = Workflow.from_yaml(yaml_str)
+            >>> my_workflow = Workflow.from_yaml(yaml_str)
         """
         return cls._from_yaml(yaml_str, _ModelWorkflow)
 
@@ -485,8 +485,8 @@ def from_file(cls, yaml_file: Union[Path, str]) -> ModelMapperMixin:
         """Create a Workflow from a Workflow contained in a YAML file.
 
         Usage:
-            yaml_file = Path(...)
-            my_workflow = Workflow.from_file(yaml_file)
+            >>> yaml_file = Path(...)
+            >>> my_workflow = Workflow.from_file(yaml_file)
         """
         return cls._from_file(yaml_file, _ModelWorkflow)
 

src/hera/workflows/workflow_template.py

@@ -127,7 +127,7 @@ def from_yaml(cls, yaml_str: str) -> ModelMapperMixin:
         """Create a WorkflowTemplate from a WorkflowTemplate contained in a YAML string.
 
         Usage:
-            my_workflow_template = WorkflowTemplate.from_yaml(yaml_str)
+            >>> my_workflow_template = WorkflowTemplate.from_yaml(yaml_str)
         """
         return cls._from_yaml(yaml_str, _ModelWorkflowTemplate)
 
@@ -136,8 +136,8 @@ def from_file(cls, yaml_file: Union[Path, str]) -> ModelMapperMixin:
         """Create a WorkflowTemplate from a WorkflowTemplate contained in a YAML file.
 
         Usage:
-            yaml_file = Path(...)
-            my_workflow_template = WorkflowTemplate.from_file(yaml_file)
+            >>> yaml_file = Path(...)
+            >>> my_workflow_template = WorkflowTemplate.from_file(yaml_file)
         """
         return cls._from_file(yaml_file, _ModelWorkflowTemplate)