feat: improve update_docs for openapi schema #2169

drbh · 2024-07-02T14:48:02Z

This PR aims to help sync the openapi schema ~~via a combination of pre-commit hooks and a new cli arg to dump the spec file~~

This PR now updates update_doc.py to have two commands allowing callers to update the launcher docs and or the openapi spec

python update_doc.py -h
usage: update_doc.py [-h] {openapi,md} ...

Update documentation for text-generation-launcher

positional arguments:
  {openapi,md}
    openapi     Update OpenAPI documentation
    md          Update launcher and supported models

options:
  -h, --help    show this help message and exit

Narsil · 2024-07-02T16:41:56Z

.github/workflows/autodocs.yaml

+    - name: Install Protoc
+      uses: arduino/setup-protoc@v1
+    - name: Clean unused files
+      run: |
+        sudo rm -rf /usr/local/lib/android # will release about 10 GB if you don't need Android
+        sudo rm -rf /usr/share/dotnet # will release about 20GB if you don't need .NET


Where is that coming from ?Feels very random I don't think it' anywhere in our current CI.

yea it is strange but was in tests.yml here

text-generation-inference/.github/workflows/tests.yaml

Lines 41 to 46 in 0759ec4

- name: Install Protoc

uses: arduino/setup-protoc@v1

- name: Clean unused files

run: |

sudo rm -rf /usr/local/lib/android # will release about 10 GB if you don't need Android

sudo rm -rf /usr/share/dotnet # will release about 20GB if you don't need .NET

In general I'd love to avoid rebuilding the server in this workflow, but it may be needed for this check

Narsil · 2024-07-02T16:42:15Z

docs/openapi.json

@@ -192,7 +190,6 @@
          "Text Generation Inference"
        ],
        "summary": "Generate a stream of token using Server-Sent Events",


Why are the descriptions gone ?

this is related to an upstream change where utopia added support for a custom description instead of using the same value for both description and summary (related PRs juhaku/utoipa#781 and juhaku/utoipa#948).

Narsil · 2024-07-02T16:42:49Z

docs/openapi.json

-            "example": "user"
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/TextMessage"


Feels the cleaner types also help here, no ?

Narsil · 2024-07-02T16:43:54Z

update_doc.py



 if __name__ == "__main__":
-    main()
+    parser = argparse.ArgumentParser(


Can we keep the simpler version that just checks everything by default ?
instead just add check_openapi function ?

yep that makes sense, updated in the latest commits

Narsil · 2024-07-02T16:44:47Z

update_doc.py


-    args = parser.parse_args()
+    process = subprocess.Popen(
+        ["text-generation-launcher"],


Can we use an extremely small model ?

Maybe to simplify we could add a flag in router in order to print the openapi directly ?
Would remove the necessity to compile things (except the router).

I know I said internally I didn't like that option, but I also said after that you were right since I didn't have a better idea.

updated and added a text-generation-router print-schema command that prints the api docs as JSON and exits, if no command is passed it goes through the normal flow

Narsil · 2024-07-02T17:09:41Z

update_doc.py

+        json.dump(new_data, f, indent=2)
+
+
+def compare_openapi(old_data, new_data):


Honestly I wouldn't even ever parse the files and simply reuse some simple diffing.

diff = subprocess.run( ["diff", tmp, filename], capture_output=True ).stdout.decode("utf-8") print(diff)

Not strong opinion, your code seems to provide cleaner output, but given the unreadableness of the original JSON file, I'm not sure it's worth potentially making mistakes in that diff algorithm.

good points! I think diff is a better long term solution and the pr has been updated to use diff

* feat: add pre commit step to force schema update when router changes * fix: prefer improved update_doc and start server and compare * fix: adjust typo * fix: adjust revert typo * fix: update workflow to use update_doc md command * feat: improve workflow to check openapi schema too * fix: adjust timeout for CI * fix: adjust raise condition and install server in ci * fix: install protoc before server * feat: improve update doc and add command to print router schema * fix: adjust autodoc workflow * fix: explicitly install protoc and python * fix: alllow trailing space in openapi schema diff

drbh added 8 commits July 2, 2024 14:47

feat: add pre commit step to force schema update when router changes

7b34ba3

fix: prefer improved update_doc and start server and compare

36bd48c

fix: adjust typo

f5f5c23

fix: adjust revert typo

ba87834

fix: update workflow to use update_doc md command

bc74571

feat: improve workflow to check openapi schema too

007c830

fix: adjust timeout for CI

a1c92bd

fix: adjust raise condition and install server in ci

aaa8991

drbh changed the title ~~feat: add pre commit step to force schema update when router changes~~ feat: improve update_docs for openapi schema Jul 2, 2024

fix: install protoc before server

caa4401

Narsil reviewed Jul 2, 2024

View reviewed changes

drbh added 4 commits July 2, 2024 18:01

feat: improve update doc and add command to print router schema

e4161a1

fix: adjust autodoc workflow

26eb7ce

fix: explicitly install protoc and python

2d0bd1a

fix: alllow trailing space in openapi schema diff

fc2ce1c

drbh marked this pull request as ready for review July 2, 2024 20:41

drbh mentioned this pull request Jul 2, 2024

Update specification #2165

Closed

Narsil approved these changes Jul 3, 2024

View reviewed changes

Narsil merged commit 571530d into main Jul 3, 2024
8 of 9 checks passed

Narsil deleted the add-pre-commit-for-openapi-schema branch July 3, 2024 07:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: improve update_docs for openapi schema #2169

feat: improve update_docs for openapi schema #2169

drbh commented Jul 2, 2024 •

edited

Loading

Narsil Jul 2, 2024

drbh Jul 2, 2024

Narsil Jul 2, 2024

drbh Jul 2, 2024

Narsil Jul 2, 2024

Narsil Jul 2, 2024

drbh Jul 2, 2024

Narsil Jul 2, 2024

Narsil Jul 2, 2024

drbh Jul 2, 2024

Narsil Jul 2, 2024 •

edited

Loading

drbh Jul 2, 2024

	- name: Install Protoc
	uses: arduino/setup-protoc@v1
	- name: Clean unused files
	run: \|
	sudo rm -rf /usr/local/lib/android # will release about 10 GB if you don't need Android
	sudo rm -rf /usr/share/dotnet # will release about 20GB if you don't need .NET

		json.dump(new_data, f, indent=2)


		def compare_openapi(old_data, new_data):

feat: improve update_docs for openapi schema #2169

feat: improve update_docs for openapi schema #2169

Conversation

drbh commented Jul 2, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Narsil Jul 2, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

drbh commented Jul 2, 2024 •

edited

Loading

Narsil Jul 2, 2024 •

edited

Loading