docs(ui): organise and update docs

This commit is contained in:
psychedelicious 2023-04-05 23:48:21 +10:00
parent 8f12ec659c
commit 591d6bcdda
4 changed files with 63 additions and 28 deletions

View File

@ -8,6 +8,7 @@
- [Getting the JSON with a python script](#getting-the-json-with-a-python-script) - [Getting the JSON with a python script](#getting-the-json-with-a-python-script)
- [Generate the API client](#generate-the-api-client) - [Generate the API client](#generate-the-api-client)
- [The generated client](#the-generated-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). 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 ```bash
# from the repo root # from the repo root
python invokeai/frontend/web/src/services/generate_openapi_json.py python invokeai/app/util/generate_openapi_json.py
mv openapi.json invokeai/frontend/web/ mv invokeai/app/util/openapi.json invokeai/frontend/web/services/fixtures/
``` ```
#### Generate the API client #### Generate the API client
@ -76,3 +77,11 @@ The client will be written to `invokeai/frontend/web/services/api/`:
- `axios` client - `axios` client
- TS types - TS types
- An easily parseable schema, which we can use to generate UI - 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`.

View File

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

View File

@ -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: <https://github.com/chakra-ui/chakra-ui/issues/7394>
### 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.

View File

@ -1,20 +1,16 @@
# InvokeAI Web UI # InvokeAI Web UI
- [InvokeAI Web UI](#invokeai-web-ui) - [InvokeAI Web UI](#invokeai-web-ui)
- [Details](#details) - [Stack](#stack)
- [Contributing](#contributing) - [Contributing](#contributing)
- [Dev Environment](#dev-environment) - [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) - [Production builds](#production-builds)
The UI is a fairly straightforward Typescript React app. The only really fancy stuff is the Unified Canvas. 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. 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). 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` 2. Start the InvokeAI UI per usual: `invokeai --web`
3. Point your browser to the dev server address e.g. <http://localhost:5173/> 3. Point your browser to the dev server address e.g. <http://localhost:5173/>
#### `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: <https://github.com/chakra-ui/chakra-ui/issues/7394>
##### `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 ### Production builds
For a number of technical and logistical reasons, we need to commit UI build artefacts to the repo. For a number of technical and logistical reasons, we need to commit UI build artefacts to the repo.