Skip to content

Add developer documentation #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 39 commits into from
Oct 26, 2022
Merged

Add developer documentation #60

merged 39 commits into from
Oct 26, 2022

Conversation

adamziel
Copy link
Collaborator

Replaces #52

This PR aims to help new contributors get started by providing the necessary developer documentation. The proposed markdown file is a start but it needs more work before merging – feel free to jump in, comment, and update as you see fit.

The doc in this PR is all about the internal structure of this project. Documenting public-facing APIs doesn't make sense at this point as the project is still early, has no stable public API, and needs more contributors.

Related to #12

cc @dd32 @gziolo @StevenDufresne @eliot-akira

@adamziel adamziel added the [Type] Documentation Improvements or additions to documentation label Oct 22, 2022
@eliot-akira
Copy link
Collaborator

eliot-akira commented Oct 22, 2022

This section of the PR description in #57 ("Monorepo") looks useful as reference.

The new packages:

* **php-wasm** – low-level WASM PHP primitives
  
  * A configurable PHP build pipeline for different targets (web, node.js, standalone)
  * A low-level `PHP` JavaScript class with `eval` for executing PHP code and FS utils like `writeFile` for runtime managing the
  * A `PHPServer` JavaScript class for dispatching HTTP requests – both to run the PHP files AND to download static files
  * A `PHPBrowser` JavaScript class to consume the above using an iframe

* **php-wasm-browser** – a high-level layer to efficiently run `php-wasm` in the browser
  
  * `service-worker` utilities to redirect the browser traffic to `PHPServer`
  * `worker-thread` utilities to offload the `PHPServer` to a separate process. Three backends are available: Iframe, Webworker, SharedWorker.
  * A messaging layer and setup helpers to connect the above.
  * Server utilities to serve the correct headers for the `wasm` files via `.htaccess`.

* **wordpress-wasm** – WordPress-specific WASM PHP bindings for web and node.js
  
  * The required WordPress-specific setup like constants and filters
  * `wp.data` bundling pipeline for the web configurable to bundle custom code
  * WordPress API to ease common tasks like login, install a plugin, start a block editor with specific settings and content
  * A `fetch`-based transport for HTTP requests
  * An example app demonstrating WordPress in the browser. Let's eventually extract it into a separate package or at least a directory.

@adamziel adamziel force-pushed the dev-docs branch 4 times, most recently from 176280c to 843de34 Compare October 25, 2022 19:40
@adamziel adamziel changed the title [WIP] Add developer documentation Add developer documentation Oct 26, 2022
@adamziel adamziel marked this pull request as ready for review October 26, 2022 09:25
@adamziel
Copy link
Collaborator Author

adamziel commented Oct 26, 2022

As I wrote these docs, many ideas stood out to me as overly complex. This PR got polluted with code refactoring, but so be it – there isn't much value in separating them at this point.

I'll go ahead and merge even though this PR could use some polish. There is almost no documentation at the moment and even unpolished docs can onboard new contributors .

Follow-up work:

  • Iterate on the existing 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 package documentation
  • Fill-in any remaining blanks

@adamziel adamziel merged commit a7d27a8 into trunk Oct 26, 2022
@adamziel adamziel deleted the dev-docs branch October 26, 2022 09:33
adamziel added a commit that referenced this pull request Nov 7, 2022
This PR populates /docs with a step-by-step documentation connecting the priors documentation efforts shipped in:

* API Reference documentation #63
* Migrate the project to TypeScript #61
* Add developer documentation  #60
* Monorepo #57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
[Type] Documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants