phoenix-oss/llama-stack
1
0
Fork 0
forked from phoenix-oss/llama-stack-mirror
Code Pull requests Releases Packages 2 Activity Actions

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

Browse source 
# 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.
This commit is contained in:
Xi Yan 2024-11-22 17:54:32 -08:00 • committed by GitHub
parent 1b2b32f959
commit d97cfaa9d9
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 80 additions and 44 deletions
Download patch file Download diff file Expand all files Collapse all files

8
docs/openapi_generator/generate.py
View file

@ -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.""",
),
),
)

8
docs/openapi_generator/pyopenapi/generator.py
View file

@ -438,6 +438,14 @@ class Generator:
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()

2
docs/requirements.txt
View file

@ -7,3 +7,5 @@ sphinx-pdj-theme
sphinx-copybutton
sphinx-tabs
sphinx-design
sphinxcontrib-openapi
sphinxcontrib-redoc

39
docs/resources/llama-stack-spec.html
View file

@ -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"
]
},

40
docs/resources/llama-stack-spec.yaml
View file

@ -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:

16
docs/source/conf.py
View file

@ -25,6 +25,7 @@ extensions = [
"sphinx_copybutton",
"sphinx_tabs.tabs",
"sphinx_design",
"sphinxcontrib.redoc",
]
myst_enable_extensions = ["colon_fence"]
@ -82,3 +83,18 @@ html_theme_options = {
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"

7
docs/source/references/api_reference/index.md Normal file
View file

@ -0,0 +1,7 @@
# API Reference
```{eval-rst}
.. sphinxcontrib-redoc:: ../resources/llama-stack-spec.yaml
:page-title: API Reference
:expand-responses: all
```

4
docs/source/references/index.md
View file

@ -1,11 +1,15 @@
# References
- [API Reference](api_reference/index) for the Llama Stack API specification
- [Llama CLI](llama_cli_reference/index) for building and running your Llama Stack server
- [Llama Stack Client CLI](llama_stack_client_cli_reference/index) for interacting with your Llama Stack server
```{toctree}
:maxdepth: 2
:hidden:
api_reference/index
llama_cli_reference/index
llama_stack_client_cli_reference/index
llama_cli_reference/download_models
```