HHVM and Hack User Documentation
There are three keys areas to this repo:
- User Documentation: The guides. We realized that finding out how to do simple things like setting up HHVM to more complicated things like using
asyncwere more tedious than they should be. The documentation should be a friend, not a nuisance.
- API Reference: We use our own HHVM code documentation for Hack and HHVM specific API documentation. And for anything PHP specific, we defer to php.net. This serves two purposes:
- The HHVM source code is the source of truth
- We don't duplicate PHP documentation, and their documentation will serve as the source of truth for PHP-specific documentation
- Infrastructure: An easier, more modular and scalable way for documentation. Markdown, not docbook, for user-guide content. Easy to follow, Hack-based source code for building the site.
Our strategy to create better documentation begins with a re-thinking of our doc infrastructure.
- Markdown instead of docbook provides an easier path for documentation source readability and updates.
- Have extensions to support things like example insertion, etc.
- Token scan our the HHVM code block documentation (instead of reflection) so that rebuilding HHVM isn't necessary to update the documentation.
- Ensure the source code that builds the site is as reusable as possible, so that it has the potential to provide reusability to documentation projects beyond Hack and HHVM.
Running A Local Copy
If you just want to run a local copy of the site and do not want to make any changes whatsoever, you can run a snapshot from Docker instead of building the site:
- Install Docker
docker run -p 8080:80 -d hhvm/user-documentation; this will output a container ID
- You can then access a local copy of the documentation at
- To stop the instance, run
docker stop ID_FROM_STEP_2_ABOVE. If you don't have a copy of that ID any more, run
docker psand use the container name in the right-most column instead.
Building The Site
If you would like to build the site locally (e.g., to test your content contributions), you will need to install and configure your system to be able to build and run the site locally.
These are the basic step-by-step instructions to get you up and running. It assumes certain packages are installed on your system. Click here for detailed installation information.
- Clone this repository
php /path/to/composer.phar install# Make sure you have composer downloaded
hhvm bin/build.php# build the site!
Follow the next steps to access this build from a browser.
Running The Site From A Checkout
Configure a webserver and HHVM to serve the
public/ directory, with all
requests that don't match a file being served by
index.php. For local
development, HHVM's built-in webserver should be sufficient:
$ cd public $ hhvm -m server -p 8080 -c ../hhvm.dev.ini
Then, in your browser, go to http://localhost:8080