README.md

The Ax website was created with Docusaurus, with some customization to support tutorials, and supplemented with Sphinx for API documentation.

Dependencies

Ensure necessary dependencies are installed (ideally to your virtual env):

pip install -e ".[tutorial]"

Building (all-in-one)

For convenience we provide a single shell script to convert the tutorials and build the website in one command. Must be executed from the repository root.

./scripts/make_docs.sh

To also execute the tutorials, add the -t flag. To generate a static build add the -b flag.

-h for all options.

Building (manually)

Notebooks

Tutorials can be executed locally using the following script. This is optional for locally building the website and is slow.

python3 scripts/run_tutorials.py -w .

We convert tutorial notebooks to MDX for embedding as docs. This needs to be done before serving the website and can be done by running this script from the project root:

python3 scripts/convert_ipynb_to_mdx.py --clean

Docusaurus

You need Node >= 18.x and Yarn in order to build the Ax website.

Switch to the website dir from the project root and start the server:

cd website
yarn install
yarn start

Open http://localhost:3000 (if doesn't automatically open).

Anytime you change the contents of the page, the page should auto-update.

Sphinx

Sphinx is used to generate an API reference from the source file docstrings. In production we use ReadTheDocs to build and host these docs, but they can also be built locally for testing.

cd sphinx/
make html

The build output is in sphinx/build/html/ but Sphinx does not provide a server. Here's a serving example using Python:

cd sphinx/build/html/
python3 -m http.server 8000

Publishing

The site is hosted on GitHub pages, automatically deployed using the Github deploy-pages action - see the config file for details.