This directory contains the Sphinx configuration for the documentation that is published to https://docs.ifcopenshell.org. It covers both the Python API, which is generated by autoapi from the source tree, and the C++ API, which is generated by Doxygen, Breathe, and Exhale. The TypeScript reference is generated by TypeDoc and rendered by Sphinx using MyST, so all three references share the same theme, navigation, and search.

• Python 3.12 or newer
• Doxygen (for the C++ API reference)
• Graphviz (for the C++ API reference diagrams)

Install the Python dependencies from this directory:

python -m pip install -r requirements.txt

Both doxygen and dot must be available on PATH. For the standard Windows install locations, this can be done for the current PowerShell session with:

$env:Path = "C:\Program Files\doxygen\bin;C:\Program Files\Graphviz\bin;$env:Path"

Before running Sphinx, stage the native WASM artifacts and generate the TypeScript pages from the repository root (Node.js 24 and npm are required):

cd src/ts/ifcopenshell-wasm
npm ci
npm run stage
cd ../ifcopenshell-js
npm ci
npm run docs:sphinx
cd ../../../docs

Set IFCOPENSHELL_WASM_DIR to your native WASM build output directory if it is outside the default build/Linux/wasm or build/Darwin/wasm layout. These artifacts include the generated TypeScript declarations used by TypeDoc.

From this directory, run:

make html

On Windows, use make.bat html instead, or invoke Sphinx directly:

python -m sphinx -M html . _build

Exhale runs Doxygen as part of the build, so there is no separate Doxygen step. The generated documentation is written to _build/html/index.html, and the Doxygen XML and Exhale sources are kept under output/ as build artifacts.

To include the current Git commit in Doxygen's project metadata, set PROJECT_NUMBER before building. For example, in PowerShell:

$env:PROJECT_NUMBER = git rev-parse --short HEAD
make html

Alternatively, configure the main CMake project with -DBUILD_DOCUMENTATION=ON and build the docs target.

To skip the slow Python API generation when building the Docker image, run this from the repository root:

docker build -f docker/docs.Dockerfile --build-arg SKIP_PYTHON_API=1 -t ifcos-docs .

The default is SKIP_PYTHON_API=0, which builds all API references. Setting it to 1 disables AutoAPI and omits the Python API reference from navigation, while still building the C++ and TypeScript references and Python guides. Links from guides to the omitted reference may produce Sphinx warnings. For a local Sphinx build, set the environment variable SKIP_PYTHON_API=1.

To preview the built documentation, run:

make server