Add developer documentation

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"