[docs] add openapi spec to docs (#508)

# What does this PR do? - modify openapi generator to add coming soon tag for unimplemented api - sphinx-redocs extension for openapi spec to readthedocs page ## Test Plan https://github.com/user-attachments/assets/b4c7eebc-2361-4198-a987-dbfbcff914cf ## Before submitting - [ ] This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case). - [ ] Ran pre-commit to handle lint / formatting issues. - [ ] Read the [contributor guideline](https://github.com/meta-llama/llama-stack/blob/main/CONTRIBUTING.md), Pull Request section? - [ ] Updated relevant documentation. - [ ] Wrote necessary unit or integration tests.
meta-llama · Nov 23, 2024 · d97cfaa · d97cfaa
1 parent 1b2b32f
commit d97cfaa
Show file tree

Hide file tree

Showing 8 changed files with 80 additions and 44 deletions.
diff --git a/docs/openapi_generator/generate.py b/docs/openapi_generator/generate.py
@@ -52,13 +52,11 @@ def main(output_dir: str):
         Options(
             server=Server(url="http://any-hosted-llama-stack.com"),
             info=Info(
-                title="[DRAFT] Llama Stack Specification",
+                title="Llama Stack Specification",
                 version=LLAMA_STACK_API_VERSION,
-                description="""This is the specification of the llama stack that provides
+                description="""This is the specification of the Llama Stack that provides
                 a set of endpoints and their corresponding interfaces that are tailored to
-                best leverage Llama Models. The specification is still in draft and subject to change.
-                Generated at """
-                + now,
+                best leverage Llama Models.""",
             ),
         ),
     )

diff --git a/docs/openapi_generator/pyopenapi/generator.py b/docs/openapi_generator/pyopenapi/generator.py
@@ -438,6 +438,14 @@ def _build_extra_tag_groups(
         return extra_tags
 
     def _build_operation(self, op: EndpointOperation) -> Operation:
+        if op.defining_class.__name__ in [
+            "SyntheticDataGeneration",
+            "PostTraining",
+            "BatchInference",
+        ]:
+            op.defining_class.__name__ = f"{op.defining_class.__name__} (Coming Soon)"
+            print(op.defining_class.__name__)
+
         doc_string = parse_type(op.func_ref)
         doc_params = dict(
             (param.name, param.description) for param in doc_string.params.values()

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -7,3 +7,5 @@ sphinx-pdj-theme
 sphinx-copybutton
 sphinx-tabs
 sphinx-design
+sphinxcontrib-openapi
+sphinxcontrib-redoc
diff --git a/docs/resources/llama-stack-spec.html b/docs/resources/llama-stack-spec.html
@@ -19,9 +19,9 @@
             spec = {
     "openapi": "3.1.0",
     "info": {
-        "title": "[DRAFT] Llama Stack Specification",
+        "title": "Llama Stack Specification",
         "version": "alpha",
-        "description": "This is the specification of the llama stack that provides\n                a set of endpoints and their corresponding interfaces that are tailored to\n                best leverage Llama Models. The specification is still in draft and subject to change.\n                Generated at 2024-11-19 09:14:01.145131"
+        "description": "This is the specification of the Llama Stack that provides\n                a set of endpoints and their corresponding interfaces that are tailored to\n                best leverage Llama Models. Generated at 2024-11-22 17:23:55.034164"
     },
     "servers": [
         {
@@ -44,7 +44,7 @@
                     }
                 },
                 "tags": [
-                    "BatchInference"
+                    "BatchInference (Coming Soon)"
                 ],
                 "parameters": [
                     {
@@ -84,7 +84,7 @@
                     }
                 },
                 "tags": [
-                    "BatchInference"
+                    "BatchInference (Coming Soon)"
                 ],
                 "parameters": [
                     {
@@ -117,7 +117,7 @@
                     }
                 },
                 "tags": [
-                    "PostTraining"
+                    "PostTraining (Coming Soon)"
                 ],
                 "parameters": [
                     {
@@ -1079,7 +1079,7 @@
                     }
                 },
                 "tags": [
-                    "PostTraining"
+                    "PostTraining (Coming Soon)"
                 ],
                 "parameters": [
                     {
@@ -1117,7 +1117,7 @@
                     }
                 },
                 "tags": [
-                    "PostTraining"
+                    "PostTraining (Coming Soon)"
                 ],
                 "parameters": [
                     {
@@ -1155,7 +1155,7 @@
                     }
                 },
                 "tags": [
-                    "PostTraining"
+                    "PostTraining (Coming Soon)"
                 ],
                 "parameters": [
                     {
@@ -1193,7 +1193,7 @@
                     }
                 },
                 "tags": [
-                    "PostTraining"
+                    "PostTraining (Coming Soon)"
                 ],
                 "parameters": [
                     {
@@ -1713,7 +1713,7 @@
                     }
                 },
                 "tags": [
-                    "PostTraining"
+                    "PostTraining (Coming Soon)"
                 ],
                 "parameters": [
                     {
@@ -2161,7 +2161,7 @@
                     }
                 },
                 "tags": [
-                    "PostTraining"
+                    "PostTraining (Coming Soon)"
                 ],
                 "parameters": [
                     {
@@ -2201,7 +2201,7 @@
                     }
                 },
                 "tags": [
-                    "SyntheticDataGeneration"
+                    "SyntheticDataGeneration (Coming Soon)"
                 ],
                 "parameters": [
                     {
@@ -3861,7 +3861,8 @@
                         "type": "string",
                         "enum": [
                             "bing",
-                            "brave"
+                            "brave",
+                            "tavily"
                         ],
                         "default": "brave"
                     },
@@ -8002,7 +8003,7 @@
             "description": "<SchemaDefinition schemaRef=\"#/components/schemas/BatchCompletionResponse\" />"
         },
         {
-            "name": "BatchInference"
+            "name": "BatchInference (Coming Soon)"
         },
         {
             "name": "BenchmarkEvalTaskConfig",
@@ -8256,7 +8257,7 @@
             "description": "<SchemaDefinition schemaRef=\"#/components/schemas/PhotogenToolDefinition\" />"
         },
         {
-            "name": "PostTraining"
+            "name": "PostTraining (Coming Soon)"
         },
         {
             "name": "PostTrainingJob",
@@ -8447,7 +8448,7 @@
             "description": "<SchemaDefinition schemaRef=\"#/components/schemas/SyntheticDataGenerateRequest\" />"
         },
         {
-            "name": "SyntheticDataGeneration"
+            "name": "SyntheticDataGeneration (Coming Soon)"
         },
         {
             "name": "SyntheticDataGenerationResponse",
@@ -8558,7 +8559,7 @@
             "name": "Operations",
             "tags": [
                 "Agents",
-                "BatchInference",
+                "BatchInference (Coming Soon)",
                 "DatasetIO",
                 "Datasets",
                 "Eval",
@@ -8568,12 +8569,12 @@
                 "Memory",
                 "MemoryBanks",
                 "Models",
-                "PostTraining",
+                "PostTraining (Coming Soon)",
                 "Safety",
                 "Scoring",
                 "ScoringFunctions",
                 "Shields",
-                "SyntheticDataGeneration",
+                "SyntheticDataGeneration (Coming Soon)",
                 "Telemetry"
             ]
         },

diff --git a/docs/resources/llama-stack-spec.yaml b/docs/resources/llama-stack-spec.yaml
@@ -2629,6 +2629,7 @@ components:
           enum:
           - bing
           - brave
+          - tavily
           type: string
         input_shields:
           items:
@@ -3397,11 +3398,10 @@ components:
       - api_key
       type: object
 info:
-  description: "This is the specification of the llama stack that provides\n     \
+  description: "This is the specification of the Llama Stack that provides\n     \
     \           a set of endpoints and their corresponding interfaces that are tailored\
-    \ to\n                best leverage Llama Models. The specification is still in\
-    \ draft and subject to change.\n                Generated at 2024-11-19 09:14:01.145131"
-  title: '[DRAFT] Llama Stack Specification'
+    \ to\n                best leverage Llama Models. Generated at 2024-11-22 17:23:55.034164"
+  title: Llama Stack Specification
   version: alpha
 jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
 openapi: 3.1.0
@@ -3658,7 +3658,7 @@ paths:
                 $ref: '#/components/schemas/BatchChatCompletionResponse'
           description: OK
       tags:
-      - BatchInference
+      - BatchInference (Coming Soon)
   /alpha/batch-inference/completion:
     post:
       parameters:
@@ -3683,7 +3683,7 @@ paths:
                 $ref: '#/components/schemas/BatchCompletionResponse'
           description: OK
       tags:
-      - BatchInference
+      - BatchInference (Coming Soon)
   /alpha/datasetio/get-rows-paginated:
     get:
       parameters:
@@ -4337,7 +4337,7 @@ paths:
                 $ref: '#/components/schemas/PostTrainingJobArtifactsResponse'
           description: OK
       tags:
-      - PostTraining
+      - PostTraining (Coming Soon)
   /alpha/post-training/job/cancel:
     post:
       parameters:
@@ -4358,7 +4358,7 @@ paths:
         '200':
           description: OK
       tags:
-      - PostTraining
+      - PostTraining (Coming Soon)
   /alpha/post-training/job/logs:
     get:
       parameters:
@@ -4382,7 +4382,7 @@ paths:
                 $ref: '#/components/schemas/PostTrainingJobLogStream'
           description: OK
       tags:
-      - PostTraining
+      - PostTraining (Coming Soon)
   /alpha/post-training/job/status:
     get:
       parameters:
@@ -4406,7 +4406,7 @@ paths:
                 $ref: '#/components/schemas/PostTrainingJobStatusResponse'
           description: OK
       tags:
-      - PostTraining
+      - PostTraining (Coming Soon)
   /alpha/post-training/jobs:
     get:
       parameters:
@@ -4425,7 +4425,7 @@ paths:
                 $ref: '#/components/schemas/PostTrainingJob'
           description: OK
       tags:
-      - PostTraining
+      - PostTraining (Coming Soon)
   /alpha/post-training/preference-optimize:
     post:
       parameters:
@@ -4450,7 +4450,7 @@ paths:
                 $ref: '#/components/schemas/PostTrainingJob'
           description: OK
       tags:
-      - PostTraining
+      - PostTraining (Coming Soon)
   /alpha/post-training/supervised-fine-tune:
     post:
       parameters:
@@ -4475,7 +4475,7 @@ paths:
                 $ref: '#/components/schemas/PostTrainingJob'
           description: OK
       tags:
-      - PostTraining
+      - PostTraining (Coming Soon)
   /alpha/providers/list:
     get:
       parameters:
@@ -4755,7 +4755,7 @@ paths:
                 $ref: '#/components/schemas/SyntheticDataGenerationResponse'
           description: OK
       tags:
-      - SyntheticDataGeneration
+      - SyntheticDataGeneration (Coming Soon)
   /alpha/telemetry/get-trace:
     get:
       parameters:
@@ -4863,7 +4863,7 @@ tags:
 - description: <SchemaDefinition schemaRef="#/components/schemas/BatchCompletionResponse"
     />
   name: BatchCompletionResponse
-- name: BatchInference
+- name: BatchInference (Coming Soon)
 - description: <SchemaDefinition schemaRef="#/components/schemas/BenchmarkEvalTaskConfig"
     />
   name: BenchmarkEvalTaskConfig
@@ -5044,7 +5044,7 @@ tags:
 - description: <SchemaDefinition schemaRef="#/components/schemas/PhotogenToolDefinition"
     />
   name: PhotogenToolDefinition
-- name: PostTraining
+- name: PostTraining (Coming Soon)
 - description: <SchemaDefinition schemaRef="#/components/schemas/PostTrainingJob"
     />
   name: PostTrainingJob
@@ -5179,7 +5179,7 @@ tags:
 - description: <SchemaDefinition schemaRef="#/components/schemas/SyntheticDataGenerateRequest"
     />
   name: SyntheticDataGenerateRequest
-- name: SyntheticDataGeneration
+- name: SyntheticDataGeneration (Coming Soon)
 - description: 'Response from the synthetic data generation. Batch of (prompt, response,
     score) tuples that pass the threshold.
 
@@ -5262,7 +5262,7 @@ x-tagGroups:
 - name: Operations
   tags:
   - Agents
-  - BatchInference
+  - BatchInference (Coming Soon)
   - DatasetIO
   - Datasets
   - Eval
@@ -5272,12 +5272,12 @@ x-tagGroups:
   - Memory
   - MemoryBanks
   - Models
-  - PostTraining
+  - PostTraining (Coming Soon)
   - Safety
   - Scoring
   - ScoringFunctions
   - Shields
-  - SyntheticDataGeneration
+  - SyntheticDataGeneration (Coming Soon)
   - Telemetry
 - name: Types
   tags:

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -25,6 +25,7 @@
     "sphinx_copybutton",
     "sphinx_tabs.tabs",
     "sphinx_design",
+    "sphinxcontrib.redoc",
 ]
 myst_enable_extensions = ["colon_fence"]
 
@@ -82,3 +83,18 @@
 html_static_path = ["../_static"]
 # html_logo = "../_static/llama-stack-logo.png"
 html_style = "../_static/css/my_theme.css"
+
+redoc = [
+    {
+        "name": "Llama Stack API",
+        "page": "references/api_reference/index",
+        "spec": "../resources/llama-stack-spec.yaml",
+        "opts": {
+            "suppress-warnings": True,
+            # "expand-responses": ["200", "201"],
+        },
+        "embed": True,
+    },
+]
+
+redoc_uri = "https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"
diff --git a/docs/source/references/api_reference/index.md b/docs/source/references/api_reference/index.md
@@ -0,0 +1,7 @@
+# API Reference
+
+```{eval-rst}
+.. sphinxcontrib-redoc:: ../resources/llama-stack-spec.yaml
+   :page-title: API Reference
+   :expand-responses: all
+```