Add sphinxcontrib-phpdomain extension

[matbcvo]

Description

This PR adds the sphinxcontrib-phpdomain extension to the documentation build.

Compared to the older phpdomain, the markstory/sphinxcontrib-phpdomain package is actively maintained.

https://github.com/markstory/sphinxcontrib-phpdomain

Screenshots or screen recordings

Before

After

[matbcvo]

@adiati98, this seems to be working based on this PR's URL:
https://mautic-developer--269.org.readthedocs.build/en/269/plugins/config.html#advanced-routing

But I can see an issue: those aren't nested correctly. Each php:method should be inside the class directive's body, indented more than the class line. We'll need to fix all instances where this occurs.

Incorrect example

Advanced routing
================

Configure custom routes through writing a listener to the ``\Mautic\CoreBundle\CoreEvents::BUILD_ROUTE`` event. Listeners to this event receives a ``Mautic\CoreBundle\Event\RouteEvent`` object. Mautic dispatches an event for each firewall when compiling routes.

.. php:class:: Mautic\CoreBundle\Event\RouteEvent

.. php:method:: getType()

    :returns: The :ref:`route firewall<plugins/config:Routing firewalls>` for the given route collection.
    :returntype: string

.. php:method:: getCollection()

    :returns: Returns a RouteCollection object that can be used to manually define custom routes.
    :returntype: \\Symfony\\Component\\Routing\\RouteCollection

.. php:method:: addRoutes(string $path)

    Load custom routes through a resource file such as yaml or XML.

    :param string $path: Path to the resource file. For example, ``@FMElfinderBundle/Resources/config/routing.yaml``.
    :returntype: void

Correct example

Advanced routing
================

Configure custom routes through writing a listener to the ``\Mautic\CoreBundle\CoreEvents::BUILD_ROUTE`` event. Listeners to this event receives a ``Mautic\CoreBundle\Event\RouteEvent`` object. Mautic dispatches an event for each firewall when compiling routes.

.. php:class:: Mautic\CoreBundle\Event\RouteEvent

  .. php:method:: getType()

      :returns: The :ref:`route firewall<plugins/config:Routing firewalls>` for the given route collection.
      :returntype: string

  .. php:method:: getCollection()

      :returns: Returns a RouteCollection object that can be used to manually define custom routes.
      :returntype: \\Symfony\\Component\\Routing\\RouteCollection

  .. php:method:: addRoutes(string $path)

      Load custom routes through a resource file such as yaml or XML.

      :param string $path: Path to the resource file. For example, ``@FMElfinderBundle/Resources/config/routing.yaml``.
      :returntype: void

[adiati98]

Hey @matbcvo,

Thanks so much for your PR! ✨
I'm currently reviewing this, but I also have a question in paralel.

[adiati98]

question: Is there any reason to remove this? Would we need this in the future?

[matbcvo]

question: Is there any reason to remove this? Would we need this in the future?

This PR switches to pipx inject because sphinx-rtd-theme and sphinxcontrib-phpdomain are Sphinx extensions, not standalone tools.

With the previous pipx install sphinx-rtd-theme, the theme was placed into its own isolated environment. While Sphinx was still able to see the theme, the sphinxcontrib-phpdomain extension was not discoverable there (resulting in module not found error). Injecting both into the sphinx environment ensures they are installed alongside Sphinx and reliably available during docs builds.

This approach keeps the extensions in the same environment as Sphinx, avoids discovery issues, and results in a cleaner, more maintainable setup.

[adiati98]

Ah, okay. Thanks so much for the explanation!

[adiati98]

Thank you for adding the pipx inject and fixing the indentation, @matbcvo! 🚀

FYI, as the build failed, we need to wait for @RCheesley to merge this.