Update API documentation (NVIDIA#71)

This PR has the following parts:
- Add categories for codes and decoders in the API section
- Promote pre-built code section by one level
- Fix the build_docs.sh script

---------

Signed-off-by: Melody Ren <[email protected]>

docs/README.md

@@ -32,8 +32,7 @@ configured by the settings in the [sphinx/conf.py](./sphinx/conf.py) file.
   bindings for the CUDA-QX API. Doc comments are defined as part of
   defining these bindings in C++. To incorporate the API documentation, the
   `cudaqx` Python package needs to be built and installed prior to generating the
-  CUDA-QX documentation. The [build_docs.sh](../scripts/build_docs.sh)
-  script will automatically do that if necessary. This project generates
+  CUDA-QX documentation. This project generates
   ReStructuredText documentation from Python `docstrings` using `autodoc`.
   The generated `.rst` files are in `docs/source/apidoc`. The files are
   generated automatically by `doc-build` and `doc-clean` will remove them.

docs/sphinx/api/qec/cpp_api.rst

@@ -1,15 +1,16 @@
 CUDA-Q QEC C++ API
 ******************************
 
-.. doxygentypedef:: cudaq::qec::float_t
+Code
+=============
 
-.. doxygenstruct:: cudaq::qec::decoder_result
+.. doxygenclass:: cudaq::qec::code
     :members:
 
-.. doxygenclass:: cudaq::qec::decoder
+.. doxygenstruct:: cudaq::qec::patch
     :members:
 
-.. doxygenstruct:: cudaq::qec::patch
+.. doxygenclass:: cudaq::qec::repetition::repetition
     :members:
 
 .. doxygenclass:: cudaq::qec::steane::steane
@@ -21,12 +22,22 @@ CUDA-Q QEC C++ API
 .. doxygenclass:: cudaq::qec::surface_code::surface_code
     :members:
 
-.. doxygenclass:: cudaq::qec::repetition::repetition
+
+Decoder
+=============
+
+.. doxygenclass:: cudaq::qec::decoder
     :members:
 
-.. doxygenclass:: cudaq::qec::code
+.. doxygenstruct:: cudaq::qec::decoder_result
     :members:
 
+
+Common
+=============
+
+.. doxygentypedef:: cudaq::qec::float_t
+
 .. doxygenenum:: cudaq::qec::operation
 
 .. doxygenfunction:: cudaq::qec::sample_code_capacity(const cudaqx::tensor<uint8_t> &, std::size_t, double)

docs/sphinx/api/qec/python_api.rst

@@ -4,15 +4,24 @@ CUDA-Q QEC Python API
 .. automodule:: cudaq_qec
     :members:
 
+Code
+=============
+
 .. autoclass:: cudaq_qec.Code
     :members:
 
+Decoder
+=============
+
 .. autoclass:: cudaq_qec.Decoder
     :members:
 
 .. autoclass:: cudaq_qec.DecoderResult
     :members:
 
+Common
+=============
+
 .. autofunction:: cudaq_qec.sample_memory_circuit
 
 .. autofunction:: cudaq_qec.sample_code_capacity

docs/sphinx/components/qec/introduction.rst

@@ -384,13 +384,14 @@ To use an implemented code:
         // The code can now be used for various numerical
         // experiments - see section below.
 
-Pre-built Quantum Error Correction Codes
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pre-built QEC Codes
+-------------------
 
 CUDA-Q QEC provides several well-studied quantum error correction codes out of the box. Here's a detailed overview of each:
 
 Steane Code
-~~~~~~~~~~~
+^^^^^^^^^^^
 
 The Steane code is a ``[[7,1,3]]`` CSS (Calderbank-Shor-Steane) code that encodes
 one logical qubit into seven physical qubits with a code distance of 3.
@@ -428,7 +429,7 @@ Usage:
         auto steane = cudaq::qec::get_code("steane");
 
 Repetition Code
-~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^
 The repetition code is a simple [[n,1,n]] code that protects against
 bit-flip (X) errors by encoding one logical qubit into n physical qubits, where n is the code distance.
 
@@ -956,8 +957,8 @@ Example of running a memory experiment:
           }
         }
 
-Additional Noise Models:
-~~~~~~~~~~~~~~~~~~~~~~~~
+Additional Noise Models
+~~~~~~~~~~~~~~~~~~~~~~~
 
 .. tab:: Python
 

scripts/build_docs.sh

@@ -39,14 +39,55 @@ docs_build_output="$repo_root/build/docs"
 sphinx_output_dir="$docs_build_output/sphinx"
 doxygen_output_dir="$docs_build_output/doxygen"
 dialect_output_dir="$docs_build_output/Dialects"
+
+# Clean up any previous build output and then recreate the build directory
 rm -rf "$docs_build_output"
+mkdir -p "$docs_build_output"
+
 doxygen_exe=doxygen
 
+# Create the conf.py file needed by Sphinx
+echo "Generating conf.py ..."
+sphinx_conf_in="$repo_root/docs/sphinx/conf.py.in"
+sphinx_conf="$repo_root/docs/sphinx/conf.py"
+
+# Verify that the input file exists before proceeding
+if [ ! -f "$sphinx_conf_in" ]; then
+  echo "Error: Sphinx configuration template '$sphinx_conf_in' does not exist." >&2
+  exit 1
+fi
+
+# Replace placeholders of the form @VAR@ in the template file with their variable values.
+CUDAQ_INSTALL_DIR=${CUDAQ_INSTALL_DIR:-"$HOME/.cudaq"}
+CMAKE_BINARY_DIR="$repo_root/build"
+SPHINX_SOURCE="$repo_root/docs/sphinx"
+
+sed -e "s|@CUDAQ_INSTALL_DIR@|${CUDAQ_INSTALL_DIR}|g" \
+    -e "s|@CMAKE_BINARY_DIR@|${CMAKE_BINARY_DIR}|g" \
+    -e "s|@SPHINX_SOURCE@|${SPHINX_SOURCE}|g" \
+    "$sphinx_conf_in" > "$sphinx_conf"
+
+echo "Configuration file created at: $sphinx_conf"
+
 # Generate API documentation using Doxygen
 echo "Generating XML documentation using Doxygen..."
 mkdir -p "${doxygen_output_dir}"
-sed 's@${DOXYGEN_OUTPUT_PREFIX}@'"${doxygen_output_dir}"'@' "$repo_root/docs/Doxyfile.in" | \
-sed 's@${CUDAQX_REPO_ROOT}@'"${repo_root}"'@' > "${doxygen_output_dir}/Doxyfile"
+doxygen_input="$repo_root/docs/Doxyfile.in"
+
+# Get all the headers
+CUDAQX_ALL_LIBS="solvers qec"
+lib_headers=""
+lib_headers="$lib_headers $(find "$repo_root/libs/core/include" -name "*.h")"
+# Add headers from each library
+for lib in $CUDAQX_ALL_LIBS; do
+    lib_headers="$lib_headers $(find "$repo_root/libs/${lib}/include" -name "*.h")"
+done
+doxygen_input=$(echo "$lib_headers" | tr '\n' ' ')
+
+sed -e "s|@DOXYGEN_OUTPUT_DIR@|${doxygen_output_dir}|g" \
+    -e "s|@DOXYGEN_INPUT@|${doxygen_input}|g" \
+    "$repo_root/docs/Doxyfile.in" > "${doxygen_output_dir}/Doxyfile"
+
 "$doxygen_exe" "${doxygen_output_dir}/Doxyfile" 2> "$logs_dir/doxygen_error.txt" 1> "$logs_dir/doxygen_output.txt"
 doxygen_exit_code=$?
 if [ ! "$doxygen_exit_code" -eq "0" ]; then
@@ -67,7 +108,10 @@ cp -r "$doxygen_output_dir" sphinx/_doxygen/
 # cp -r "$dialect_output_dir" sphinx/_mdgen/ # uncomment once we use the content from those files
 
 rm -rf "$sphinx_output_dir"
-sphinx-build -v -n -W --keep-going -b html sphinx "$sphinx_output_dir" -j auto #2> "$logs_dir/sphinx_error.txt" 1> "$logs_dir/sphinx_output.txt"
+sphinx-build -v -n  --keep-going -b html \
+  -Dbreathe_projects.cudaqx="${doxygen_output_dir}/xml" \
+  sphinx "$sphinx_output_dir" -j auto #2> "$logs_dir/sphinx_error.txt" 1> "$logs_dir/sphinx_output.txt"
+
 sphinx_exit_code=$?
 if [ ! "$sphinx_exit_code" -eq "0" ]; then
     echo "Failed to generate documentation using sphinx-build."