Rework c++ docs

docs/cpp-api/README.md

@@ -1,33 +1,56 @@
 # IfcOpenShell C++ API documentation
 
-This folder contains the setup to build the IfcOpenShell C++ API documentation from the source code.
+This directory contains the Sphinx, Doxygen, Breathe, and Exhale configuration
+for the IfcOpenShell C++ API reference. During a Sphinx build, Exhale runs
+Doxygen, Breathe consumes the generated XML, and Exhale creates the API pages.
+
+## Prerequisites
+
+- Python 3.10 or newer
+- [Doxygen](https://www.doxygen.nl/)
+- [Graphviz](https://graphviz.org/)
+
+Install the Python dependencies from this directory:
+
+```shell
+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:
+
+```powershell
+$env:Path = "C:\Program Files\doxygen\bin;C:\Program Files\Graphviz\bin;$env:Path"
+```
 
 ## Generating the documentation
 
-> Prerequisites:
-> 
-> Make sure to have [Doxygen](https://www.doxygen.nl) and [Graphviz](https://graphviz.org) installed into your `$PATH` variable.
-> 
-> The documentation also use the [doxygen-awesome](https://jothepro.github.io/doxygen-awesome-css) theme as a git submodule.
-
-Build with the command (from within the `/docs/cpp-api` folder):
+From this directory, run:
 
 ```shell
-$ doxygen
+python -m sphinx -M html . output -W --keep-going
 ```
 
-To include the current git commit hash into the build documentation, use the following command:
+To include the current Git commit in Doxygen's project metadata, set
+`PROJECT_NUMBER` before building. For example, in PowerShell:
+
+```powershell
+$env:PROJECT_NUMBER = git rev-parse --short HEAD
+python -m sphinx -M html . output -W --keep-going
+```
+
+Or in a POSIX shell:
 
 ```shell
-$ PROJECT_NUMBER=$(git rev-parse --short HEAD) doxygen
+PROJECT_NUMBER=$(git rev-parse --short HEAD) python -m sphinx -M html . output -W --keep-going
 ```
 
-This will extract the current commit hash in short version and sets the propper ENV variable used by doxygen.
+Alternatively, configure the main CMake project with
+`-DBUILD_DOCUMENTATION=ON` and build the `cpp_api_docs` target.
 
-The generation of the documentation might take a while depending on your systems hardware, as it is configured to generate the Class graphs using .
+The generated documentation is written to `output/html/index.html`. The
+generated Doxygen XML and Exhale sources are kept under `output/` as build
+artifacts.
 
-The resulting documentation is located unter `/cpp-api/output/html` and can be directly accessed with your browser:
-
-```shell
-$ open ./output/html/index.html
-```
+The generated headers under `src/ifcparse/schemas` are intentionally excluded
+from this documentation build.