Fix image handling for RTD builds (#260)

* Fix image handling for RTD builds

- Implement automatic image collection from multiple source locations
- Add path fixing for included markdown files (source and doctree level)
- Use builder-inited event for reliable image copying timing
- Add build output copying to ensure images are available in HTML
- Fix HTML paths to use relative paths for local file viewing
- Remove debug code and update README with image handling instructions

This fix ensures images work correctly on both branch and main RTD builds,
as well as local builds. The solution is generic and works for any
contributor adding images anywhere in the documentation.

Tested and verified on both test branch and main branch RTD builds.

* fix: remove unused os imports in image handling functions

Addresses review comment: 'Unused import.'

Removed unused 'import os' statements from:
- fix_included_image_paths_source()
- fix_included_image_paths_doctree()
- copy_images_to_build_output()

* fix: use specific exceptions instead of generic Exception catch

Addresses review comments:
- 'Should handle specific errors here. Examples: PermissionError, FileNotFoundError'
- 'Isn't this the same as shutil.SameFileError?'

Changed exception handling in image copy operations:
- Use shutil.SameFileError for same-file scenarios (silently skip)
- Catch PermissionError and FileNotFoundError specifically
- Removed string matching on error messages

* fix: prefix unused Sphinx event parameters with underscore

Addresses review comment: 'I think app and docname are not used within
this scope. Please check.'

In fix_included_image_paths_source(), the 'app' and 'docname' parameters
are required by Sphinx's source-read event signature but not used in the
function body. Prefixed with underscore to indicate intentional non-use.

Added docstring Args section to document this design decision.

* feat: add support for image titles in markdown image syntax

Addresses review comment: Support images with titles like ![alt](path "Title").

Updated the regex pattern to handle both:
- Basic images: ![alt](path)
- Images with titles: ![alt](path "Title")

The regex now:
- Extracts the path separately from the optional title
- Preserves the title in the fixed output path
- Handles all existing path patterns correctly

Tested with various scenarios including paths with spaces and titles.

Author: pritkc

doc/sphinx/README.md

@@ -147,19 +147,18 @@ This process is handled by the `build.sh` script, which is called by the `doc-la
 
 ### Image Handling
 
-Images are automatically handled when building the documentation using the Makefile targets:
-
-The image handling process:
-- Copies images from `doc/assets/img/` to `doc/sphinx/build/html/_static/img/`
-- Fixes image paths in the HTML output
-- For PDF output, converts SVG files to high-quality PDFs (using Inkscape)
-
-If you're running Sphinx directly without the Makefile, you'll need to run the image copy script separately:
-
-```bash
-# Run after building documentation manually
-./copy_images.sh
-```
+Images are automatically handled during the build process. The system automatically:
+
+- **Collects images** from multiple locations:
+  - `doc/assets/img/` (main image directory)
+  - `source/math_functions/figures/` (math function figures)
+  - `source/api/examples/md/figures/` (example figures)
+  - Any `figures/` directory next to markdown files
+- **Copies images** to `source/_images/` (standard Sphinx location)
+- **Fixes image paths** in included markdown files automatically
+- **For PDF output**: Converts SVG files to high-quality PDFs using Inkscape
+
+**For contributors**: Simply place images in `doc/assets/img/` or a `figures/` directory next to your markdown file, and reference them using standard markdown syntax: `![Alt text](doc/assets/img/image.png)` or `![Alt text](figures/image.png)`. The build system handles everything else automatically.
 
 ## Development Workflow