The repo for hhvm.com. This contains the website, blog and HHVM/Hack documentation. You'll need HHVM 3.0 or greater, and have SQLite installed.

Contributing to HHVM and Hack Manual Documentation

You agree to license any contributions that you make to the HHVM and Hack Manual Documentation under the Creative Commons Attribution 3.0 License found at http://creativecommons.org/licenses/by/3.0/legalcode.

To update or add documentation

The docs live in __docs/phpdoc/en. The .xml files and associated directories here are basically the top level outline for the documents. The key ones are language and reference.

You will update .xml files. See __docs/phpdoc/doc-base/README for instructions on how to get started. Or just look at the .xml files that already exist and copypasta as much as you need to.

If you are adding a new high level topic or extension, you will probably have to add it to doc-base/manual.xml.in as well. manual.xml and .manual.xml are autogenerated by the validation process below.

To validate your additions or changes

To make sure all the XML you have changed or added jives (both in legit XML and in context with the structure of the documentation), you need to run the validator.

The validator is in __docs/phpdoc/doc-base/configure.php. Since HHVM 3.3, we have disabled entity loading by default. Instead we whitelist entity types that are allowed. Thus, we have a .ini file to specify those entity types.

To run it:

hhvm -c ../phpdoc.ini configure.php

If successful, this will update the __docs/phpdoc/doc-base/.manual.xml file that is basically all of the .xml files squashed together. This file will be used to render the .php files that will actually serve the site.

If unsuccessful, you will see errors. You can run

php configure.php --enable-xml-details

for more detailed XML information.

To render into PHP files

After validation, it is now time to render the docs to be served. Note that even if you have not made any changes to the documents, you must run the validation step above to generate the .manual.xml file.

In __docs/phd:

hhvm render.php -d ../phpdoc/doc-base/.manual.xml -f php -P PHP -o ../../manual/en

The .php files will outputted to the manual/en directory.

To speed up validation, you can try something like: hhvm render.php -d ../phpdoc/doc-base/.manual.xml -f php -P PHP -o ../../manual/en -t -p language.hack to only render topics that you changed. However, this is not really shippable yet. So before pushing, do a full validation. This is good for quick iteration.

Serve-up the files locally.

Run a local HHVM server in the root directory, so that /manual is a top level path. Navigate to http://<your local sandbox>/manual/en.

Scripts to help.

There are some sample scripts to make this process easier:

__docs/phpdoc/doc-base/scripts/validate-docs-sample __docs/phd/util/render-docs-sample

Other helpful links

https://wiki.php.net/doc/howto/faq https://wiki.php.net/doc/howto/structure