Update module repos and generate docs

Author: eliot-akira

docs/pages/modules/fields/index.md

@@ -59,9 +59,11 @@ cd fields
 Install dependencies:
 
 ```sh
-composer install & npm ci
+npm ci
 ```
 
+### JS and CSS
+
 Build for development - watch files for changes and rebuild
 
 ```sh
@@ -88,7 +90,7 @@ Start a local test site using [`wp-now`](https://github.com/WordPress/playground
 npm run start
 ```
 
-For convenience, this also concurrently builds for development and watches files to rebuild.
+For convenience, this also concurrently runs `npm run dev`.
 
 ### Dev dependencies
 
@@ -124,14 +126,14 @@ Mainly it's useful for mounting local folders into the virtual file system. For
 
 This module comes with a suite of unit and integration tests.
 
-`composer install --dev` will install PHPUnit.
-
 #### Method 1: Cloning wordpress-develop.git (Previous)
 
 You will need a copy of https://github.com/WordPress/wordpress-develop.git available. You can run `git clone https://github.com/WordPress/wordpress-develop.git` in this directory as this is where the bootstrap script expects it to be by default (the `WORDPRESS_DEVELOP_DIR` environment variable overrides this path).
 
 Bootstrap the WordPress development environment by running `npm i; npm run build:dev`. Then copy wp-tests-config-sample.php to wp-tests-config.php inside the wordpress-develop directory and set the database credentials as needed. **WARNING!** This database is **dropped** everytime the tests run. Do not use a production database.
 
+To install PHPUnit with this method, run `composer install`. You'll need `composer` installed globally.
+
 Run `vendor/bin/phpunit` to launch the tests and hope for all green ;)
 
 Unit and integration tests are mixed together (as is usual in WordPress) and can be found in tests/phpunit/cases and its subdirectories. Every case is in a class extending a TestCase, every test should be a public function starting with "test". We prefer snake case.
@@ -146,33 +148,59 @@ https://docs.phpunit.de/en/9.6/ for more information.
 
 Alternatively, you can use the [wp-env](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) tool to quickly spin up a local dev and test environment, optionally switching between multiple PHP versions.
 
-Please note that `wp-env` requires Docker to be installed. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/), [macOS](https://docs.docker.com/desktop/install/mac-install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
+The test environment is started by running:
+
+```sh
+npm run env:start
+```
 
-This repository includes NPM scripts to run the tests with PHP versions 8.2 and 7.4. 
+This uses [`wp-env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) to quickly spin up a local dev and test environment, optionally switching between multiple PHP versions. `wp-env` requires Docker to be installed. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/), [macOS](https://docs.docker.com/desktop/install/mac-install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
 
-**Note**: We need to maintain compatibility with PHP 7.4, as WordPress itself only has “beta support” for PHP 8.x. See https://make.wordpress.org/core/handbook/references/php-compatibility-and-wordpress-versions/ for more information.
+Visit [http://localhost:8888](http://localhost:8888) to see the dev site, and [http://localhost:8889](http://localhost:8880) for the test site, whose database is cleared on every run.
 
-If you’re on Windows, you might have to use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to run the tests (see [this comment](https://bitbucket.org/tangibleinc/tangible-fields-module/pull-requests/30#comment-389568162)).
+Before running tests, install PHPUnit as a dev dependency using Composer in the container.
 
-To run the tests with Docker installed:
+```sh
+npm run env:composer:install
 ```
-npm install
+
+To run the tests:
+
+```sh
 npm run env:test:8.2
 npm run env:test:7.4
 ```
 
 The version-specific commands take a while to start, but afterwards you can run npm run env:test to re-run tests in the same environment.
 
 To stop the Docker process:
-```
+
+```sh
 npm run env:stop
 ```
 
 To “destroy” and remove cache:
-```
+
+```sh
 npm run env:destroy
 ```
 
+#### Notes
+
+To run more than one instance of `wp-env`, set different ports for the dev and test sites:
+
+```sh
+WP_ENV_PORT=3333 WP_ENV_TESTS_PORT=3334 npm run env:start
+```
+
+---
+
+This repository includes NPM scripts to run the tests with PHP versions 8.2 and 7.4. We need to maintain compatibility with PHP 7.4, as WordPress itself only has “beta support” for PHP 8.x. See https://make.wordpress.org/core/handbook/references/php-compatibility-and-wordpress-versions/ for more information.
+
+---
+
+If you’re on Windows, you might have to use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to run the tests (see [this comment](https://bitbucket.org/tangibleinc/tangible-fields-module/pull-requests/30#comment-389568162)).
+
 ### Jest
 
 We rely on Jest to test the frontend side of the module:

docs/pages/modules/framework/index.md

@@ -12,7 +12,7 @@ Many of these were refactored from the deprecated [plugin framework v2](https://
 
 #### Source code
 
-The framework is developed within the [Template System](https://github.com/tangibleinc/template-system). It is also published as [its own repository](https://github.com/tangibleinc/framework) to support plugins installing it as a Composer module.
+Git repository: https://github.com/tangibleinc/framework
 
 ## Modules
 
@@ -27,3 +27,220 @@ The framework is developed within the [Template System](https://github.com/tangi
 - [Object](object)
 - [Plugin](plugin)
 - [Select](select)
+
+## Develop
+
+Prerequisites: [Git](https://git-scm.com/), [Node](https://nodejs.org/en/) (version 18 and above)
+
+Clone the repository and install dependencies.
+
+```sh
+git clone git@github.com:tangibleinc/framework.git
+cd framework
+npm install
+```
+
+### JS and CSS
+
+Build for development - watch files for changes and rebuild
+
+```sh
+npm run dev
+```
+
+Build for production
+
+```sh
+npm run build
+```
+
+Format to code standard
+
+```sh
+npm run format
+```
+
+#### Build modules for development
+
+Watch files for changes and rebuild.
+
+```sh
+npm run dev [module1 module2..]
+```
+
+Press CTRL + C to stop.
+
+#### Build modules for production
+
+Builds minified bundles with source maps.
+
+```sh
+npm run build [module1 module2..]
+```
+
+#### Format code
+
+Format files to code standard with [Prettier](https://prettier.io) and [PHP Beautify](https://github.com/tangibleinc/php-beautify).
+
+```sh
+npm run format [module1 module2..]
+```
+
+### Local dev site
+
+Start a local dev site using [`wp-now`](https://github.com/WordPress/playground-tools/blob/trunk/packages/wp-now/README.md).
+
+```sh
+npm run start
+```
+
+Press CTRL + C to stop.
+
+#### Dev dependencies
+
+Optionally, install dev dependencies such as third-party plugins before starting the site.
+
+```sh
+npm run install:dev
+```
+
+To keep them updated, run:
+
+```sh
+npm run update:dev
+```
+
+#### Customize environment
+
+Create a file named `.wp-env.override.json` to customize the WordPress environment. This file is listed in `.gitignore` so it's local to your setup.
+
+Mainly it's useful for mounting local folders into the virtual file system. For example, to link another plugin in the parent directory:
+
+```json
+{
+  "mappings": {
+    "wp-content/plugins/example-plugin": "../example-plugin"
+  }
+}
+```
+
+## Tests
+
+This plugin comes with a suite of unit and integration tests.
+
+The test environment is started by running:
+
+```sh
+npm run env:start
+```
+
+This uses [`wp-env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/) to quickly spin up a local dev and test environment, optionally switching between multiple PHP versions. It requires **Docker** to be installed. There are instructions available for installing Docker on [Windows](https://docs.docker.com/desktop/install/windows-install/), [macOS](https://docs.docker.com/desktop/install/mac-install/), and [Linux](https://docs.docker.com/desktop/install/linux-install/).
+
+Visit [http://localhost:8888](http://localhost:8888) to see the dev site, and [http://localhost:8889](http://localhost:8880) for the test site, whose database is cleared on every run.
+
+Before running tests, install PHPUnit as a dev dependency using Composer inside the container.
+
+```sh
+npm run env:composer:install
+```
+
+Composer will add and remove folders in the `vendor` folder, based on `composer.json` and `composer.lock`. If you have any existing Git repositories, ensure they don't have any work in progress before running the above command.
+
+Run the tests:
+
+```sh
+npm run env:test
+```
+
+For each PHP version:
+
+```sh
+npm run env:test:7.4
+npm run env:test:8.2
+```
+
+The version-specific commands take a while to start, but afterwards you can run `npm run env:test` to re-run tests in the same environment.
+
+To stop the Docker process:
+
+```sh
+npm run env:stop
+```
+
+To remove Docker containers, volumes, images associated with the test environment.
+
+```sh
+npm run env:destroy
+```
+
+#### Notes
+
+To run more than one instance of `wp-env`, set different ports for the dev and test sites:
+
+```sh
+WP_ENV_PORT=3333 WP_ENV_TESTS_PORT=3334 npm run env:start
+```
+
+---
+
+This repository includes NPM scripts to run the tests with PHP versions 8.2 and 7.4. We need to maintain compatibility with PHP 7.4, as WordPress itself only has “beta support” for PHP 8.x. See https://make.wordpress.org/core/handbook/references/php-compatibility-and-wordpress-versions/ for more information.
+
+---
+
+If you’re on Windows, you might have to use [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to run the tests (see [this comment](https://bitbucket.org/tangibleinc/tangible-fields-module/pull-requests/30#comment-389568162)).
+
+### End-to-end tests
+
+The folder `/tests/e2e` contains end-to-end-tests using [Playwright](https://playwright.dev/docs/intro) and [WordPress E2E Testing Utils](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-e2e-test-utils-playwright/).
+
+#### Prepare
+
+Before the first time you run it, install the browser engine.
+
+```sh
+npx playwright install chromium
+```
+
+#### Run
+
+Run the tests. This will start the local WordPress environment with `wp-env` as needed. Then Playwright starts a browser engine to interact with the test site.
+
+```sh
+npm run test:e2e
+```
+
+#### Watch mode
+
+There is a "Watch mode", where it will watch the test files for changes and re-run them. 
+This provides a helpful feedback loop when writing tests, as a kind of test-driven development. Press CTRL + C to stop the process.
+
+```sh
+npm run test:e2e:watch
+```
+
+A common usage is to have terminal sessions open with `npm run dev` (build assets and watch to rebuild) and `npm run tdd` (run tests and watch to re-run).
+
+#### UI mode
+
+There's also "UI mode" that opens a browser interface to see the tests run.
+
+```sh
+npm run test:e2e:ui
+```
+
+#### Utilities
+
+Here are the common utilities used to write the tests.
+
+- `test` - https://playwright.dev/docs/api/class-test
+- `expect` - https://playwright.dev/docs/api/class-genericassertions
+- `admin` - https://github.com/WordPress/gutenberg/tree/trunk/packages/e2e-test-utils-playwright/src/admin
+- `page` - https://playwright.dev/docs/api/class-page
+- `request` - https://playwright.dev/docs/api/class-apirequestcontext
+
+#### References
+
+Examples of how to write end-to-end tests:
+
+- WordPress E2E tests - https://github.com/WordPress/wordpress-develop/blob/trunk/tests/e2e
+- Gutenberg E2E tests - https://github.com/WordPress/gutenberg/tree/trunk/test/e2e