Add installation troubleshooting

stfc · Jan 13, 2025 · c2cd80a · c2cd80a
1 parent 1d79227
commit c2cd80a
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 0 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -31,6 +31,7 @@
     "sphinx.ext.viewcode",
     "sphinxcontrib.contentui",
     "sphinx_copybutton",
+    "sphinx_collapse",
 ]
 
 numpydoc_validation_checks = {"all", "EX01", "SA01", "ES01"}

diff --git a/docs/source/user_guide/troubleshooting.rst b/docs/source/user_guide/troubleshooting.rst
@@ -2,6 +2,45 @@
 Troubleshooting
 ===============
 
+Installation
+------------
+
+When installing ``janus-core``, CMake errors can occur when building ``phonopy``, such as:
+
+.. collapse:: Example CMake error
+
+    .. code-block:: bash
+
+        CMake Error at /tmp/pip-build-env-j2jx9pp5/overlay/lib/python3.11/site-packages/nanobind/cmake/nanobind-config.cmake:243 (target_compile_features):
+            target_compile_features The compiler feature "cxx_std_17" is not known to
+            CXX compiler
+
+            "GNU"
+
+            version 4.8.5.
+        Call Stack (most recent call first):
+            /tmp/pip-build-env-j2jx9pp5/overlay/lib/python3.11/site-packages/nanobind/cmake/nanobind-config.cmake:358 (nanobind_build_library)
+            CMakeLists.txt:108 (nanobind_add_module)
+
+
+        -- Configuring incomplete, errors occurred!
+
+        *** CMake configuration failed
+        [end of output]
+
+        note: This error originates from a subprocess, and is likely not a problem with pip.
+        ERROR: Failed building wheel for phonopy
+        Building wheel for python-hostlist (setup.py) ... done
+        Created wheel for python-hostlist: filename=python_hostlist-2.2.1-py3-none-any.whl size=39604 sha256=44f9f27a42895e61a521cf9129a6a3ad03e633b201390da5ef76d5f59db3b94f
+        Stored in directory: ...
+        Successfully built janus-core python-hostlist
+        Failed to build phonopy
+        ERROR: ERROR: Failed to build installable wheels for some pyproject.toml based projects (phonopy)
+
+
+This can typically be resolved by ensuring your C++ compiler is updated, and that the `CXX <https://cmake.org/cmake/help/latest/envvar/CXX.html>`_ environment variable is set.
+
+
 Carbon tracking
 ---------------
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -83,6 +83,7 @@ docs = [
     "sphinxcontrib-contentui<1.0.0,>=0.2.5",
     "sphinxcontrib-details-directive<1.0,>=0.1",
     "sphinx-copybutton<1.0.0,>=0.5.2",
+    "sphinx-collapse>=0.1.3",
 ]
 
 pre-commit = [