From 47e109b5c0f93afe232453252ee09c7aa068720f Mon Sep 17 00:00:00 2001
From: Oliver Hamlet <git@ortham.net>
Date: Wed, 11 Jun 2025 18:59:59 +0100
Subject: [PATCH] Make building C++ API docs optional

If Doxygen isn't found then the C++ API reference page won't be included in the built docs.
---
 docs/README.md                                |  4 ++-
 .../{reference.rst => cpp_api_reference.rst}  |  6 ++--
 docs/api/rust_api_reference.rst               |  6 ++++
 docs/conf.py                                  | 30 ++++++++++++-------
 docs/index.rst                                |  3 +-
 5 files changed, 33 insertions(+), 16 deletions(-)
 rename docs/api/{reference.rst => cpp_api_reference.rst} (97%)
 create mode 100644 docs/api/rust_api_reference.rst

diff --git a/docs/README.md b/docs/README.md
index f209589e..18e927a8 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,11 +2,13 @@
 
 This directory contains documentation for libloot and LOOT's metadata syntax. It does not include Rust API reference documentation: that is generated using `cargo doc`.
 
-To build the documentation, install [Doxygen](https://www.doxygen.nl/), Python and [uv](https://docs.astral.sh/uv/getting-started/installation/) and make sure they're accessible from your `PATH`, then run:
+To build the documentation, install Python and [uv](https://docs.astral.sh/uv/getting-started/installation/) and make sure they're accessible from your `PATH`, then run:
 
 ```
 cd ../docs
 uv run -- sphinx-build -b html . build/html
 ```
 
+If [Doxygen](https://www.doxygen.nl/) is also installed and accessible from your `PATH`, the C++ API's reference documentation will also be included.
+
 The documentation files for dependency licenses and copyright notices are auto-generated using [cargo-attribution](https://github.com/ameknite/cargo-attribution): to regenerate them run `py scripts/licenses.py`. The script is hardcoded to generate files for the C++ wrapper's dependencies, but in practice that doesn't add any content over doing the same for just the core libloot Rust library.
diff --git a/docs/api/reference.rst b/docs/api/cpp_api_reference.rst
similarity index 97%
rename from docs/api/reference.rst
rename to docs/api/cpp_api_reference.rst
index 6ba03061..de3585b3 100644
--- a/docs/api/reference.rst
+++ b/docs/api/cpp_api_reference.rst
@@ -1,6 +1,6 @@
-*************
-API Reference
-*************
+*****************
+C++ API Reference
+*****************
 
 .. contents::
   :local:
diff --git a/docs/api/rust_api_reference.rst b/docs/api/rust_api_reference.rst
new file mode 100644
index 00000000..45412b8f
--- /dev/null
+++ b/docs/api/rust_api_reference.rst
@@ -0,0 +1,6 @@
+******************
+Rust API Reference
+******************
+
+To view the Rust API reference, run ``cargo doc --open`` from the root directory
+of a copy of the libloot source code repository.
diff --git a/docs/conf.py b/docs/conf.py
index ef4a77fd..e8df0dfe 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -20,13 +20,7 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
-import subprocess, os
-
-doxygen_output_directory = os.path.join('..', 'cpp', 'build', 'docs')
-if not os.path.exists(doxygen_output_directory):
-    os.makedirs(doxygen_output_directory)
-
-subprocess.call(['doxygen', 'Doxyfile'], cwd='../cpp')
+import shutil, subprocess, os
 
 # -- General configuration ------------------------------------------------
 
@@ -348,9 +342,23 @@ texinfo_documents = [
 #
 # texinfo_no_detailmenu = False
 
+found_doxygen = shutil.which('doxygen')
 
-breathe_projects = {
-    'loot':'../cpp/build/docs/xml/',
-}
+if found_doxygen:
+    doxygen_output_directory = os.path.join('..', 'cpp', 'build', 'docs')
+    if not os.path.exists(doxygen_output_directory):
+        os.makedirs(doxygen_output_directory)
 
-breathe_default_project = 'loot'
+    subprocess.call(['doxygen', 'Doxyfile'], cwd='../cpp')
+
+    extensions.append('breathe')
+
+    breathe_projects = {
+        'loot':'../cpp/build/docs/xml/',
+    }
+
+    breathe_default_project = 'loot'
+else:
+    # This causes Sphinx to log a warning, but it's unavoidable without
+    # modifying index.rst at runtime.
+    exclude_patterns.append('api/cpp_api_reference.rst')
diff --git a/docs/index.rst b/docs/index.rst
index b997994a..a7829316 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,7 +8,8 @@ libloot
 
   api/introduction
   api/sorting
-  api/reference
+  api/rust_api_reference
+  api/cpp_api_reference
   api/licenses/index
   api/changelog