From 591d6bcdda85e4df3e5c0fce9e48ad2d8ca8d56c Mon Sep 17 00:00:00 2001 From: psychedelicious <4822129+psychedelicious@users.noreply.github.com> Date: Wed, 5 Apr 2023 23:48:21 +1000 Subject: [PATCH] docs(ui): organise and update docs --- .../services/README.md => docs/API_CLIENT.md} | 13 +++++++-- invokeai/frontend/web/docs/EVENTS.md | 21 ++++++++++++++ invokeai/frontend/web/docs/PACKAGE_SCRIPTS.md | 29 +++++++++++++++++++ invokeai/frontend/web/{ => docs}/README.md | 28 ++---------------- 4 files changed, 63 insertions(+), 28 deletions(-) rename invokeai/frontend/web/{src/services/README.md => docs/API_CLIENT.md} (75%) create mode 100644 invokeai/frontend/web/docs/EVENTS.md create mode 100644 invokeai/frontend/web/docs/PACKAGE_SCRIPTS.md rename invokeai/frontend/web/{ => docs}/README.md (64%) diff --git a/invokeai/frontend/web/src/services/README.md b/invokeai/frontend/web/docs/API_CLIENT.md similarity index 75% rename from invokeai/frontend/web/src/services/README.md rename to invokeai/frontend/web/docs/API_CLIENT.md index 07eb0bdadf..51f3a6510c 100644 --- a/invokeai/frontend/web/src/services/README.md +++ b/invokeai/frontend/web/docs/API_CLIENT.md @@ -8,6 +8,7 @@ - [Getting the JSON with a python script](#getting-the-json-with-a-python-script) - [Generate the API client](#generate-the-api-client) - [The generated client](#the-generated-client) + - [API client customisation](#api-client-customisation) This API client is generated by an [openapi code generator](https://github.com/ferdikoomen/openapi-typescript-codegen). @@ -56,8 +57,8 @@ The script will output `openapi.json` in the repo root. Then we need to move it ```bash # from the repo root -python invokeai/frontend/web/src/services/generate_openapi_json.py -mv openapi.json invokeai/frontend/web/ +python invokeai/app/util/generate_openapi_json.py +mv invokeai/app/util/openapi.json invokeai/frontend/web/services/fixtures/ ``` #### Generate the API client @@ -76,3 +77,11 @@ The client will be written to `invokeai/frontend/web/services/api/`: - `axios` client - TS types - An easily parseable schema, which we can use to generate UI + +## API client customisation + +The generator has a default `request.ts` file that implements a base `axios` client. The generated client uses this base client. + +One shortcoming of this is base client is it does not provide response headers unless the response body is empty. To fix this, we provide our own lightly-patched `request.ts`. + +To access the headers, call `getHeaders(response)` on any response from the generated api client. This function is exported from `invokeai/frontend/web/src/services/util/getHeaders.ts`. diff --git a/invokeai/frontend/web/docs/EVENTS.md b/invokeai/frontend/web/docs/EVENTS.md new file mode 100644 index 0000000000..24f2497a20 --- /dev/null +++ b/invokeai/frontend/web/docs/EVENTS.md @@ -0,0 +1,21 @@ +# Events + +Events via `socket.io` + +## `actions.ts` + +Redux actions for all socket events. Payloads all include a timestamp, and optionally some other data. + +Any reducer (or middleware) can respond to the actions. + +## `middleware.ts` + +Redux middleware for events. + +Handles dispatching the event actions. Only put logic here if it can't really go anywhere else. + +For example, on connect we want to load images to the gallery if it's not populated. This requires dispatching a thunk, so we need to directly dispatch this in the middleware. + +## `types.ts` + +Hand-written types for the socket events. Cannot generate these from the server, but fortunately they are few and simple. diff --git a/invokeai/frontend/web/docs/PACKAGE_SCRIPTS.md b/invokeai/frontend/web/docs/PACKAGE_SCRIPTS.md new file mode 100644 index 0000000000..90d85bb540 --- /dev/null +++ b/invokeai/frontend/web/docs/PACKAGE_SCRIPTS.md @@ -0,0 +1,29 @@ +# Package Scripts + +WIP walkthrough of `package.json` scripts. + +## `theme` & `theme:watch` + +These run the Chakra CLI to generate types for the theme, or watch for code change and re-generate the types. + +The CLI essentially monkeypatches Chakra's files in `node_modules`. + +## `postinstall` + +The `postinstall` script patches a few packages and runs the Chakra CLI to generate types for the theme. + +### Patch `@chakra-ui/cli` + +See: + +### Patch `redux-persist` + +We want to persist the canvas state to `localStorage` but many canvas operations change data very quickly, so we need to debounce the writes to `localStorage`. + +`redux-persist` is unfortunately unmaintained. The repo's current code is nonfunctional, but the last release's code depends on a package that was removed from `npm` for being malware, so we cannot just fork it. + +So, we have to patch it directly. Perhaps a better way would be to write a debounced storage adapter, but I couldn't figure out how to do that. + +### Patch `redux-deep-persist` + +This package makes blacklisting and whitelisting persist configs very simple, but we have to patch it to match `redux-persist` for the types to work. diff --git a/invokeai/frontend/web/README.md b/invokeai/frontend/web/docs/README.md similarity index 64% rename from invokeai/frontend/web/README.md rename to invokeai/frontend/web/docs/README.md index 2c2b4ae36a..787725cdda 100644 --- a/invokeai/frontend/web/README.md +++ b/invokeai/frontend/web/docs/README.md @@ -1,20 +1,16 @@ # InvokeAI Web UI - [InvokeAI Web UI](#invokeai-web-ui) - - [Details](#details) + - [Stack](#stack) - [Contributing](#contributing) - [Dev Environment](#dev-environment) - - [`postinstall` script](#postinstall-script) - - [`@chakra-ui/cli` patch](#chakra-uicli-patch) - - [`redux-persist` patch](#redux-persist-patch) - - [`redux-deep-persist` patch](#redux-deep-persist-patch) - [Production builds](#production-builds) The UI is a fairly straightforward Typescript React app. The only really fancy stuff is the Unified Canvas. Code in `invokeai/frontend/web/` if you want to have a look. -## Details +## Stack State management is Redux via [Redux Toolkit](https://github.com/reduxjs/redux-toolkit). Communication with server is a mix of HTTP and [socket.io](https://github.com/socketio/socket.io-client) (with a custom redux middleware to help). @@ -44,26 +40,6 @@ Start everything in dev mode: 2. Start the InvokeAI UI per usual: `invokeai --web` 3. Point your browser to the dev server address e.g. -#### `postinstall` script - -The `postinstall` script patches a few packages and runs the Chakra-UI CLI to generate types for the theme. - -##### `@chakra-ui/cli` patch - -See: - -##### `redux-persist` patch - -We want to persist the canvas state to `localStorage` but many canvas operations change data very quickly, so we need to debounce the writes to `localStorage`. - -`redux-persist` is unfortunately unmaintained. The repo's current code is nonfunctional, but the last release's code depends on a package that was removed from `npm` for being malware, so we cannot just fork it. - -So, we have to patch it directly. Perhaps a better way would be to write a debounced storage adapter, but I couldn't figure out how to do that. - -##### `redux-deep-persist` patch - -This package makes blacklisting and whitelisting persist configs very simple, but we have to patch it to match `redux-persist` for the types to work. - ### Production builds For a number of technical and logistical reasons, we need to commit UI build artefacts to the repo.