Add docs for v5 (#500)

Signed-off-by: GitHub <[email protected]>
argoproj-labs · Mar 24, 2023 · 19efdc2 · 19efdc2
1 parent af27524
commit 19efdc2
Show file tree

Hide file tree

Showing 30 changed files with 378 additions and 356 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -24,18 +24,28 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "myst_parser",
+    "autoapi.extension",
 ]
 master_doc = "index"
 
+autoapi_type = "python"
+autoapi_dirs = ["../src/hera"]  # Starts from the `hera` module, without including `src` in the name
+autoapi_file_pattern = "*.py"
+autoapi_python_use_implicit_namespaces = True
+autoapi_add_toctree_entry = False
+
 templates_path = ["_templates"]
-exclude_patterns = [
-    "_build",
-    "Thumbs.db",
-    ".DS_Store",
-    "conftest.py",
-    "tests",
-    "\.github",
-]
+exclude_patterns = (
+    [  # uses glob-style https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-exclude_patterns
+        "_[!_]*[!_][!_].py",  # exclude private modules like `_mixins.py` but not dunder files (not working?)
+        "_build",
+        "Thumbs.db",
+        ".DS_Store",
+        "conftest.py",
+        "tests",
+        ".github",
+    ]
+)
 numpydoc_show_inherited_class_members = True
 numpydoc_show_class_members = False
 

diff --git a/...examples/workflows/upstream/cluster_workflow_template__workflow_template_ref.md b/...examples/workflows/upstream/cluster_workflow_template__workflow_template_ref.md
@@ -0,0 +1,32 @@
+# Cluster Workflow Template  Workflow Template Ref
+
+> Note: This example is a replication of an Argo Workflow example in Hera. The upstream example can be [found here](https://github.com/argoproj/argo-workflows/blob/master/examples/cluster-workflow-template/workflow-template-ref.yaml).
+
+
+
+## Hera
+
+```python
+from hera.workflows import Workflow
+from hera.workflows.models import WorkflowTemplateRef
+
+wt_ref = WorkflowTemplateRef(name="cluster-workflow-template-submittable", cluster_scope=True)
+
+w = Workflow(
+    generate_name="cluster-workflow-template-hello-world-",
+    workflow_template_ref=wt_ref,
+)
+```
+
+## YAML
+
+```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Workflow
+metadata:
+  generateName: cluster-workflow-template-hello-world-
+spec:
+  workflowTemplateRef:
+    clusterScope: true
+    name: cluster-workflow-template-submittable
+```
diff --git a/docs/examples/workflows/upstream/workflow_template__workflow_template_ref.md b/docs/examples/workflows/upstream/workflow_template__workflow_template_ref.md
@@ -12,11 +12,10 @@ from hera.workflows.models import WorkflowTemplateRef
 
 wt_ref = WorkflowTemplateRef(name="workflow-template-submittable")
 
-with Workflow(
+w = Workflow(
     generate_name="workflow-template-hello-world-",
     workflow_template_ref=wt_ref,
-) as w:
-    pass
+)
 ```
 
 ## YAML

diff --git a/docs/hera_getting_started.md b/docs/hera_getting_started.md
@@ -0,0 +1,28 @@
+# Hera
+
+## Quick Start
+
+```python
+from hera.workflows import DAG, Container, Parameter, Workflow
+
+with Workflow(
+    generate_name="dag-diamond-",
+    entrypoint="diamond",
+) as w:
+    echo = Container(
+        name="echo",
+        image="alpine:3.7",
+        command=["echo", "{{inputs.parameters.message}}"],
+        inputs=[Parameter(name="message")],
+    )
+    with DAG(name="diamond"):
+        A = echo(name="A", arguments={"message": "A"})
+        B = echo(name="B", arguments={"message": "B"})
+        C = echo(name="C", arguments={"message": "C"})
+        D = echo(name="D", arguments={"message": "D"})
+        A >> [B, C] >> D
+
+w.create()
+```
+
+## Walk Through
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,11 +6,14 @@
 Welcome to Hera's documentation!
 ================================
 
+Hera is a Python framework for constructing and submitting Argo Workflows. The main goal of Hera is to make the Argo ecosystem accessible by simplifying workflow construction and submission. Hera presents an intuitive Python interface to the underlying API of Argo, with custom classes making use of context managers and callables, empowering users to focus on their own executable payloads rather than workflow setup. Hera allows power users of Argo to use Python if preferred, by ensuring feature parity with Argo and a fallback option through an OpenAPI generated Python module found at `hera.workflows.models`.
+
+See the Examples for usage and comparison to YAML.
+
 .. toctree::
-   :maxdepth: 2
-   :caption: Hera
+   :caption: Getting Started
 
-   src
+   hera_getting_started
 
 .. toctree::
    :caption: Expr Transpilation
@@ -19,18 +22,30 @@ Welcome to Hera's documentation!
 
 .. toctree::
    :glob:
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Hera Workflow Examples
 
    examples/workflows/*
 
 .. toctree::
    :glob:
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Hera - Argo Workflow Examples Replication
 
    examples/workflows/upstream/*
 
+.. toctree::
+   :maxdepth: 3
+   :caption: Hera Workflows API Reference
+
+   hera.workflows <autoapi/hera/workflows/index>
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Hera Events API Reference
+
+   hera.events <autoapi/hera/events/index>
+
 Indices and tables
 ==================
 

diff --git a/docs/modules.rst b/docs/modules.rst
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,5 +1,6 @@
 sphinx
 sphinx-book-theme
+sphinx-autoapi
 myst-parser
 Jinja2<3.1
 # -e .  # hera itself