Docs: Fix Sphinx warnings

[tlshannon]

Description

Fix Sphinx documentation build warnings

Resolves all warnings produced by sphinx-build -n --keep-going across the QEC, solvers, and core API docs.

RST / content fixes

• Set LD_LIBRARY_PATH and PYTHONPATH to the CUDAQ install at docs-build time so that the real extension module loads. autoclass then reads docstrings from the actual nanobind-bound C++ types for the Python API.
• Add missing Doxygen directives to cpp_api.rst: sub-namespaces (decoding, decoding::config, realtime), extension macros (CUDAQ_EXTENSION_CUSTOM_CREATOR_FUNCTION*), surface-code types (surface_role, sc_orientation, vec2d), sparse_binary_matrix, graph_resources, decoder_inputs, and others.
• Add missing solvers classes (ceo, upccgsd) and fix qaoa overload signatures in solvers/cpp_api.rst.
• Exclude RST fragment files (included via .. include::) from exclude_patterns in conf.py.in to prevent duplicate domain-registration warnings.
• Fix broken cross-references: use :ref: instead of :class: for stabilizer_grid and TensorNetworkDecoder; fix a plugin → plugins typo in the TN decoder class path.
• Expand nitpick_ignore for C++ and Python types that are intentionally unresolvable (CUDA, MLIR, and cudaq types).

Build infrastructure

• Add CUDAQ_EXTENSION_CUSTOM_CREATOR_FUNCTION and _WITH_NAME to PREDEFINED in Doxyfile.in so Doxygen can parse solver observer headers without macro-expansion errors.
• Add post-build HTML sanity checks to build_docs.sh that fail the build (with distinct exit codes) if alias of, or the internal pybind11 module name appear in any generated HTML page.

Doxygen comment fixes

• graph.h: add missing @param weight to graph::add_node.
• code.h: add missing @param options to both get_code overloads.
• pcm_utils.h: add missing @param pcm to the tensor overload of get_sorted_pcm_column_indices; add missing @param num_syndromes_per_round to sort_pcm_columns and simplify_pcm.
• surface_code.h: suppress a spurious Doxygen auto-link on code::get_parity_x() in a doc comment by prefixing with %.

Runtime / performance impact

N/A

Self-review checklist

Please confirm each item before requesting review. Check [x] or strike
through and explain.

Before requesting review

• I reviewed my own full diff in GitHub or my editor.
• PR is in Draft if it is not yet ready for review.
• Temporary / debugging changes have been removed.
• Local test logs reviewed; no unexplained warnings or errors.
• CI logs reviewed; no unexplained warnings or errors.
• Full CI has been run.

Scope and size

• PR is under ~1000 lines, or an exception is justified in the description.
• Refactoring-only changes are isolated in their own PR(s).
• No existing tests were disabled or modified just to make this PR pass
  (if so, an issue has been raised).

Tests

• New functionality has new tests.
• Tests fail if the new functionality is broken (including crashes), not
  just when it is missing.
• Negative tests added where exceptions are expected.
• Truth data added where simple EXPECT_* / assert checks are
  insufficient for algorithmic correctness.
• CI runtime impact considered; team notified if significant.
• Documentation CI run: https://github.com/NVIDIA/cudaqx/actions/runs/29612690978

Documentation

• Public-facing APIs have Doxygen docs.
• User-visible behavior changes have public docs, or a follow-up is
  tracked.

Code style

• Naming follows the existing convention (snake_case vs camelCase) for
  the area being modified.

Dependencies

• No new third-party dependencies, or the team has been notified and
  OSRB tickets filed.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[tlshannon]

/ok to test 0c5d057

[bmhowe23]

The PR description is out of date with the current diffs. It claims three things that are not in the final diff: autodoc_mock_imports = ['cudaq'], manual .. class:: stubs, and setting CUDAQX_DOCS_GEN_IMPORT_CUDAQ=ON in the CMake docs target. The final approach abandoned all of these in favor of the LD_LIBRARY_PATH + real-import route (and CUDAQX_DOCS_GEN_IMPORT_CUDAQ is now referenced nowhere in the tree). Worth trimming the description so that it's accurate with the current state.

[bmhowe23]

Thanks, Tracy.