Issue with Generating PDF Documentation on ReadTheDocs – Missing baglib and sphinx/index.html

[nabolfat]

We are working to enable PDF downloads for the BAG library using ReadTheDocs. However, we are encountering build issues related to missing baglib and sphinx/index.html, preventing successful documentation generation.

Steps Taken & Observations

1. Set Up the Build Environment

• Installed all required dependencies.
• Followed the build script: https://github.com/OpenNavigationSurface/BAG/blob/master/docs/readthedocs/build.bash
• Ran the following command:

cmake -G Ninja -DCMAKE_BUILD_TYPE=Release -B ../doc-build -S ../ \
      -DPython3_FIND_STRATEGY=LOCATION \
      -DBAG_BUILD_PYTHON:BOOL=ON \
      -DBAG_BUILD_DOCS:BOOL=ON \
      -DBAG_BUILD_BAG_LIB=ON

• Output (relevant sections):

-- The C compiler identification is GNU 14.2.0
-- The CXX compiler identification is GNU 14.2.0
-- Found BAG: ~/my_conda_envs/readthedocspdf/lib/libbaglib.so
-- Found Sphinx: ~/my_conda_envs/readthedocspdf/bin/sphinx-build
-- Configuring done (0.7s)
-- Generating done (0.0s)
CMake Warning:
  Manually-specified variables were not used by the project:
    BAG_BUILD_BAG_LIB
    BAG_BUILD_DOCS
    Python3_FIND_STRATEGY
-- Build files have been written to: ~/BAG/docs/doc-build

• Observed Warnings:
  The manually specified variables BAG_BUILD_BAG_LIB, BAG_BUILD_DOCS, and Python3_FIND_STRATEGY were not used.

2. Attempted to Build the Documentation:

• Ran the following:
  cmake --build ../doc-build -v
• Error Encountered:
  ninja: error: 'baglib', needed by 'sphinx/index.html', missing and no known rule to make it

This suggests that baglib is missing or not being properly built, which blocks sphinx/index.html generation.

3. Attemped to Follow Linux Build Instructions:

• Followed https://github.com/OpenNavigationSurface/BAG/blob/master/docs/BUILDING.md
• Ran:
  cmake --build build -j 8
  Encountered Error:
  ninja: error: 'docs/sphinx/index.html', needed by 'docs/CMakeFiles/Sphinx', missing and no known rule to make it
  It seems the Sphinx documentation is not being built correctly, leading to missing files.

4. Manually Tried to Build Sphinx DOcumentation

• Attemped:
  sphinx-build -b html source build/html
• Result:
  No significant change, and the same missing file errors persist.
  We suspect that Breathe (which requires Doxygen) might be involved since there is an error referencing doxygen/xml/index.xml.

---

Questions & Assistance Needed

1. baglib Missing Issue
   Is baglib expected to be built as part of cmake -G Ninja? If so, why is it not being found in the doc-build directory?
   Are there any additional dependencies we need to explicitly build?

2. Sphinx Documentation Build Failure
   Why does sphinx/index.html fail to generate despite using the provided build scripts?
   Could there be a missing step in the documentation process?

3. Doxygen & Breathe Dependency
   Might the issue be related to Breathe requiring Doxygen XML files?
   What is the correct way to ensure that all the required files are generated before running Sphinx?

System Information

OS: Linux
Python Version: 3.12 (Conda Environment)
Sphinx Version: 6.2.1 (installed in Conda environment)
Doxygen Version: 1.12.0 (installed in Conda environment)

Thanks in advance for your help!