This repository contains the old (unmaintained) Spoofax documentation, made with Sphinx in the Read The Docs style of documentation.

This documentation is hosted at https://www.metaborg.org/en/latest/. When a commit to this repository is made, it will automatically build and update the documentation.

Sphinx requires Python, at least version 2.6. To install the required Python packages, run:

pip install -r requirements.txt --upgrade

To build the documentation, use the Makefile:

make html

which will generate HTML documentation into _build/html with _build/html/index.html as the main page.

Sphinx does incremental building if possible. If your changes are not being built for some reason, use the clean target:

make clean html

• latexpdf for a PDF version (via latex) of the documentation. A working latex distribution is required.
• epub for an epub version, an e-book format with resizable text, for tablets and e-readers.
• singlehtml for single page HTML documentation.
• text for plain-text documentation.
• help for a list of all other targets.

While making the documentation, if you get an error similar to this:

Could not import extension foo (exception: No module named foo)

Then you need to update the installed Python packages from the requirements.txt file.

If you get this error while installing the required Python packages:

*********************************************************************************
Could not find function xmlCheckVersion in library libxml2. Is libxml2 installed?
*********************************************************************************

Then you need to install lxml through easy_install instead:

easy_install lxml

After that, installing the required Python packages through pip should succeed.

If you get this error while installing the required Python packages on Windows:

error: Microsoft Visual C++ 9.0 is required (Unable to find vcvarsall.bat).

Then you need to download and install Microsoft Visual C++ Compiler for Python 2.7 from https://aka.ms/vcpython27.

If you get the error:

Failed to execute process '/usr/local/bin/pip'. Reason:
The file '/usr/local/bin/pip' specified the interpreter '/usr/local/opt/python/bin/python3.x', which is not an executable command.

Or:

/bin/sh: /usr/local/bin/sphinx-build: /usr/local/opt/python/bin/python3.x: bad interpreter: No such file or directory
make: *** [html] Error 126

Then make sure your pip installation corresponds to your python installation. Execute the following to fix:

pip3 install --upgrade pip

If you get this error:

Extension error (sphinx.ext.intersphinx):
Handler <function load_mappings at 0x10fd122a0> for event 'builder-inited' threw an exception (exception: '<' not supported between instances of 'dict' and 'dict')
make: *** [html] Error 2

Then delete your _build directory and try again.