Cpp doc

[chemiskyy]

This pull request significantly enhances the documentation build system by integrating C++ API documentation generation with Doxygen and Breathe, updating the Sphinx configuration, and improving the Makefile and CI workflow for a more robust and user-friendly experience. It also introduces new and expanded documentation pages for various modules and functions.

Documentation Build System Integration and Improvements:

• Doxygen and Breathe Integration:

  • Adds a Doxyfile for C++ API documentation generation and configures Sphinx to use Breathe for rendering Doxygen XML output. This enables seamless integration of C++ API docs into the Sphinx-generated documentation. [1] [2]
  • Updates the Makefile to automate Doxygen generation, provide new targets (e.g., doxygen, html, html-only, clean-doxy, rebuild, serve, open), and improve developer experience with detailed help output. [1] [2]
  • Modifies the Sphinx configuration (conf.py) to run Doxygen automatically if needed, set up Breathe, and suppress specific warnings for smoother builds. [1] [2] [3]

• CI Workflow Enhancements:

  • Updates the GitHub Actions workflow to install Doxygen, generate Doxygen XML before building Sphinx docs, and cache both Sphinx and Doxygen outputs for faster builds. [1] [2]
  • Adjusts build and deployment paths to use the new _build directory structure, ensuring consistency across local and CI builds. [1] [2] [3]

Expanded and New Documentation:

• C++ API Documentation:

  • Adds new reStructuredText files in docs/cpp_api/continuum_mechanics/functions/ for key C++ headers (constitutive.hpp, contimech.hpp, criteria.hpp, damage.hpp) with overviews and links to Doxygen-generated API references. [1] [2] [3] [4]

• Python API Documentation:

  • Introduces new or expanded function reference pages for hyperelasticity, recovery of elastic properties, stress conversions, and Voigt/matrix transfer helpers, improving discoverability and usability of the Python API. [1] [2] [3] [4]

Other Improvements:

• Updates Sphinx-Gallery configuration for better compatibility and maintainability.

---

Most important changes:

Documentation build system & CI integration:

• Added Doxyfile and integrated Doxygen with Sphinx via Breathe for automated C++ API documentation, including configuration in both the Makefile and conf.py. [1] [2] [3] [4]
• Updated the GitHub Actions workflow to install Doxygen, generate XML, and cache _build outputs, ensuring consistent and efficient documentation builds and deployments. [1] [2] [3] [4]

Expanded documentation content:

• Added new C++ API documentation pages with overviews and Doxygen group references for constitutive.hpp, contimech.hpp, criteria.hpp, and damage.hpp. [1] [2] [3] [4]
• Introduced or expanded Python API documentation for hyperelasticity, elastic property recovery, stress conversions, and Voigt/matrix transfer helpers. [1] [2] [3] [4]

Developer experience improvements:

• Enhanced the documentation Makefile with new targets, improved help output, and streamlined workflows for local development and CI. [1] [2]
• Updated Sphinx-Gallery configuration to avoid unpicklable objects and improve reliability.