Add developer documentation (#60)

Document the public and private APIs of all the packages in this repository.

This commit is polluted with code refactoring since many ideas stood out as overly complex while writing the docs. There isn't much value in separating them out at this point so they're here.

Follow-up work:

* Iterate on the docs, fix typos, gather more feedback, reword confusing fragments.
* Generate a proper reference doc in a markdown format. It should include the top-level module documentation, function documentation, and the classes + their methods. I'm not sure which tool can handle that correctly.
* Add the missing `wordpress-wasm` module documentation
* Fill-in any remaining blanks

Author: adamziel

README.md

@@ -1,95 +1,56 @@
 # WordPress in the browser!
 
-See 
-[the WordPress.org blog post explaining why is this useful and how does it work](https://make.wordpress.org/core/2022/09/23/client-side-webassembly-wordpress-with-no-server/) for more details. The README doc below is short&sweet for now. Also, [explore the early preview on StackBlitz](https://stackblitz.com/edit/wp-plugin-playground).
-
-![](demo.gif)
-
-
-## Running the demo
-
-This repository ships with a pre-built demo that you can just run!
+WordPress.wasm is a client-side WordPress that runs without a PHP server thanks to the magic of WebAssembly. 
 
-1. Clone this repo
-2. Run `npm install && npm run dev`
-3. Visit http://127.0.0.1:8777/
+[See the live demo!](https://wasm.wordpress.net/wordpress.html)
 
-If you want to build the assembly yourself, follow the instructions below.
-
-This repo draws inspiration from https://github.com/seanmorris/php-wasm and uses https://github.com/aaemnnosttv/wp-sqlite-db 
-
-## Building the assembly
-
-The build process is split into automated parts. The scripts below create a docker image with the necessary tools, and build  PHP as WebAssembly.
-
-### Building WASM PHP for the web
+![](demo.gif)
 
-```bash
-npm run build:php:web
-```
-### Building WASM PHP for node.js
+Table of contents:
 
-```bash
-npm run build:php:node
-```
+- [Why is this useful?](#why-is-this-useful)
+- [Getting started](#getting-started)
+- [Architecture overview](#architecture-overview)
 
-## Building custom WordPress bundle
+## Why is this useful?
 
-If you'd like to customize the packaged WordPress installation, update
-the build script at `packages/wordpress-wasm/wordpress/prepare-wordpress.sh`. It generates a bundle called `wp.data`.
+I'm glad you asked – WordPress.wasm is a big deal!
 
-For example, before the comment "Prepare WordPress static files":
+WordPress.wasm can power:
 
-- Download and extract a plugin zip package
-- Move it into `wp-content/mu-plugins`
-- Add a file that loads the plugin
+* Runeditable code examples in your documentation or course
+* Plugin and theme demos in a private WordPress instance where the user is already logged in as admin
+* Easily switching PHP and WordPress version when testing
+* Replaying and fixing the failed CI tests right in the browser
 
-```bash
-plugin_file=example-plugin.1.0.0.zip
-wget https://downloads.wordpress.org/plugin/$plugin_file
-unzip $plugin_file
-rm $plugin_file
+WordPress.wasm provides a strong foundation for the above use-cases but does not implement them just yet. This project is still in its early days and needs contributors. Become a contributor today and help us make these tools a reality!
 
-mv example-plugin wordpress/wp-content/plugins/
+See 
+[the WordPress.org blog post](https://make.wordpress.org/core/2022/09/23/client-side-webassembly-wordpress-with-no-server/) to learn about the vision, other use-cases, and the visuals.
 
-echo "<?php
-require_once ABSPATH.'wp-content/mu-plugins/example-plugin/example-plugin.php';
-" > wp-content/mu-plugins/index.php
-```
+### Getting started
 
-To generate a new bundle, run:
+You can run WordPress.wasm as follows:
 
-```bash
-npm run build:wp
+```js
+git clone https://github.com/WordPress/wordpress-wasm
+cd wordpress-wasm
+npm install
+npm run dev
 ```
 
-## How does it work?
-
-This repo uses four magic ingredients to make WordPress work in the browser:
-
-1. A WordPress configured to use SQLite instead of MySQL. This is possible thanks to https://github.com/aaemnnosttv/wp-sqlite-db.
-2. A PHP 8.0 compiled with SQLite3 support into WebAssembly.
-3. A PHP + WordPress WebAssembly bundle created using the emscripten toolkit.
-4. A service worker that loads the bundle and dispatches the regular HTTP traffic to the in-memory WordPress instance.
-
-The static files (.js, .css, etc.) are served directly from the host filesystem, not from the WebAssembly bundle.
-
-The work is *heavily* inspired by https://github.com/seanmorris/php-wasm.
-
-## Limitations
-
-The worker applies a series of strange patches to WordPress, it's unclear why they're needed at the moment.
-
-The site editor does not work at the moment. The block editor does, though.
+A browser should open and take you to your very own client-side WordPress at http://127.0.0.1:8777/wordpress.html! 
 
-PHP cannot communicate with WordPress.org so the plugin directory etc does not work.
+As of today, the best way to play with WordPress.wasm is to directly modify the cloned files – [packages/wordpress-wasm/](./packages/wordpress-wasm) is a good place to start.
 
-The sqlite database lives in the memory and the changes only live as long as the service worker.
+Why aren't there any npm packages? This is a new project and didn't get there yet – all the efforts were focused on getting it to work. If you'd like to see public npm packages sooner than later, you are more than welcome to contribute.
 
-## Future work
+## Architecture overview
 
-* Fix the workarounds mentioned above
-* Remove the static files from the wasm bundle
-* Remove unnecessary PHP extensions to lower the bundle size
+WordPress.wasm is made of the following building blocks:
 
+* [php-wasm](./packages/php-wasm) – a configurable PHP->WebAssembly build pipeline, convenient JavaScript bindings, and a PHP server implemented in JavaScript.
+* [php-wasm-browser](./packages/php-wasm-browser) – tools to run real PHP apps in the browser via `php-wasm`, like a Service Worker implementation or Worker Threads to run the PHP runtime concurrently.
+* [wordpress-wasm](./packages/wordpress-wasm) – runs WordPress in the browser using the other two packages.
 
+Consult the linked README.md files in each of these packages to learn more.

build-docs.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+
+npx docgen packages/php-wasm/src/php.js --output packages/php-wasm/README.md --to-section php.js                                                                                                            1 ↵
+npx docgen packages/php-wasm/src/php-server.js --output packages/php-wasm/README.md --to-section php-server.js
+npx docgen packages/php-wasm/src/php-browser.js --output packages/php-wasm/README.md --to-section php-browser.js
+
+npx docgen packages/php-wasm-browser/src/emscripten-download-monitor.js --output packages/php-wasm-browser/README.md --to-section Utilities --ignore defaul
+npx docgen packages/php-wasm-browser/src/worker-thread.js --output packages/php-wasm-browser/README.md --to-section 'Worker Thread API ' --ignore 'loadPHPWithProgress|currentBackend'

package.json

@@ -40,8 +40,8 @@
     "yargs": "^17.5.1"
   },
   "devDependencies": {
+    "@wordpress/docgen": "^1.29.0",
     "@wordpress/eslint-plugin": "^13.0.0",
-    "live-server": "^1.2.2",
     "chokidar-cli": "^3.0.0",
     "esbuild": "^0.15.5",
     "eslint": "8.22.0",
@@ -53,6 +53,7 @@
     "gulp": "^4.0.2",
     "gulp-rename": "^2.0.0",
     "gulp-replace": "^1.1.3",
+    "live-server": "^1.2.2",
     "npm-run-all": "^4.1.5",
     "prettier": "^2.7.1",
     "request": "^2.88.2"