Skip to content

Add sphinxcontrib-phpdomain extension #269

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Sep 15, 2025
Merged

Add sphinxcontrib-phpdomain extension #269

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
1dde4ff
Add sphinxcontrib-phpdomain extension
matbcvo Sep 12, 2025
45e49b1
Fix DDEV
matbcvo Sep 12, 2025
08dee9a
Properly nest RouteEvent methods under class
matbcvo Sep 12, 2025
7722001
Properly nest CustomButtonEvent methods under class
matbcvo Sep 12, 2025
78a8eff
Properly nest PendingEvent methods under class
matbcvo Sep 12, 2025
b2d9511
Properly nest ConditionEvent methods under class
matbcvo Sep 12, 2025
9c1d6e0
Properly nest DecisionEvent methods under class
matbcvo Sep 12, 2025
90a6d1e
Properly nest ParameterCredentialsInterface methods under class
matbcvo Sep 12, 2025
ccc2b89
Properly nest HeaderCredentialsInterface methods under class
matbcvo Sep 12, 2025
ae12cc7
Properly nest CredentialsInterface methods under class
matbcvo Sep 12, 2025
a265ed2
Properly nest Note attributes and methods under class
matbcvo Sep 12, 2025
bdccc5d
Properly nest BasicIntegration methods under class
matbcvo Sep 12, 2025
eee2c48
Properly nest AbstractMigration attribute and methods under class
matbcvo Sep 12, 2025
31cc99c
Properly nest ClassMetadataBuilder methods under class
matbcvo Sep 12, 2025
6b76372
Properly nest Translator methods under class
matbcvo Sep 12, 2025
6520771
Properly nest TriggerBuilderEvent methods under class
matbcvo Sep 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .ddev/web-build/Dockerfile.sphinx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ RUN curl -sSL https://github.com/pypa/pipx/releases/latest/download/pipx.pyz -o
RUN chmod +x /usr/local/bin/pipx

RUN pipx install --global sphinx
RUN pipx install --force --global --include-deps sphinx-rtd-theme
Copy link
Contributor

@adiati98 adiati98 Sep 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@matbcvo matbcvo Sep 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@adiati98 adiati98 Sep 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, okay. Thanks so much for the explanation!

RUN pipx inject --global sphinx sphinxcontrib-phpdomain sphinx-rtd-theme
244 changes: 122 additions & 122 deletions docs/components/campaigns.rst
View file
Open in desktop

Large diffs are not rendered by default.

18 changes: 9 additions & 9 deletions docs/components/integrations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,20 +41,20 @@ The ``HelloWorldIntegration`` needs to implement ``\Mautic\IntegrationsBundle\In

.. php:class:: \Mautic\IntegrationsBundle\Integration\BasicIntegration

.. php:method:: public function getName(): string;
.. php:method:: public function getName(): string;

:return: Return the Integration's name.
:returntype: string
:return: Return the Integration's name.
:returntype: string

.. php:method:: public function getDisplayName(): string;
.. php:method:: public function getDisplayName(): string;

:return: Return the Integration's display name.
:returntype: string
:return: Return the Integration's display name.
:returntype: string

.. php:method:: public function getIcon(): string;
.. php:method:: public function getIcon(): string;

:return: Get the path to the Integration's icon.
:returntype: string
:return: Get the path to the Integration's icon.
:returntype: string



Expand Down
36 changes: 18 additions & 18 deletions docs/components/integrations_authentication.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -165,15 +165,15 @@ To use the parameter based API key, create a credentials class that implements `

.. php:class:: \Mautic\IntegrationsBundle\Auth\Provider\ApiKey\Credentials\ParameterCredentialsInterface

.. php:method:: public function getKeyName(): string;
.. php:method:: public function getKeyName(): string;

:return: Key name.
:returntype: string
:return: Key name.
:returntype: string

.. php:method:: public function getApiKey(): ?string;
.. php:method:: public function getApiKey(): ?string;

:return: API key or null.
:returntype: ?string
:return: API key or null.
:returntype: ?string

Find the code snippet as follows,

Expand Down Expand Up @@ -221,15 +221,15 @@ To use the header based API key, create a credentials class that implements ``\M

.. php:class:: \Mautic\IntegrationsBundle\Auth\Provider\ApiKey\Credentials\HeaderCredentialsInterface

.. php:method:: public function getKeyName(): string;
.. php:method:: public function getKeyName(): string;

:return: Key name.
:returntype: string
:return: Key name.
:returntype: string

.. php:method:: public function getApiKey(): ?string;
.. php:method:: public function getApiKey(): ?string;

:return: API key or null.
:returntype: ?string
:return: API key or null.
:returntype: ?string

Find the code snippet as follows,

Expand Down Expand Up @@ -279,15 +279,15 @@ To use the basic auth, create a credentials class that implements ``\Mautic\Inte

.. php:class:: \Mautic\IntegrationsBundle\Auth\Provider\BasicAuth\CredentialsInterface

.. php:method:: public function getUsername(): ?string;
.. php:method:: public function getUsername(): ?string;

:return: User name.
:returntype: ?string
:return: User name.
:returntype: ?string

.. php:method:: public function getPassword(): ?string;
.. php:method:: public function getPassword(): ?string;

:return: Password.
:returntype: ?string
:return: Password.
:returntype: ?string

Find the code snippet as follows,

Expand Down
16 changes: 8 additions & 8 deletions docs/components/integrations_configuration_form_notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,19 +41,19 @@ Note Object

.. php:class:: \Mautic\IntegrationsBundle\DTO\Note

.. php:attr:: public note;
.. php:attr:: public note;

.. php:attr:: public type;
.. php:attr:: public type;

.. php:method:: public function getNote(): string
.. php:method:: public function getNote(): string

:return: The string to display.
:returntype: string
:return: The string to display.
:returntype: string

.. php:method:: public function getType(): string
.. php:method:: public function getType(): string

:return: The note type, this helps annotate the note.
:returntype: string
:return: The note type, this helps annotate the note.
:returntype: string

The following code snippet shows the use of ``\Mautic\IntegrationsBundle\Integration\Interfaces\ConfigFormNotesInterface``.

Expand Down
12 changes: 6 additions & 6 deletions docs/components/points.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,15 +139,15 @@ Mautic dispatches the Event ``\Mautic\PointBundle\PointEvents::TRIGGER_ON_BUILD`

.. php:class:: Mautic\PointBundle\Event\TriggerBuilderEvent

.. php:method:: public function addEvent(string $key, array $action)
.. php:method:: public function addEvent(string $key, array $action)

:param string $key: Unique key for the Action.
:param array $action: :ref:`Action definition<components/points:Custom Point Trigger definition>`.
:param string $key: Unique key for the Action.
:param array $action: :ref:`Action definition<components/points:Custom Point Trigger definition>`.

.. php:method:: public getEvents()
.. php:method:: public getEvents()

:return: Array of registered Events.
:returntype: array
:return: Array of registered Events.
:returntype: array

.. vale off

Expand Down
46 changes: 23 additions & 23 deletions docs/components/translator.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,37 +63,37 @@ In PHP templates, use ``$view['translator']`` to access the Translator service.

.. php:class:: Mautic\CoreBundle\Translation\Translator

.. php:method:: trans(string $id[, array $parameters = [], ?string $domain = null, ?string $locale = null])
.. php:method:: trans(string $id[, array $parameters = [], ?string $domain = null, ?string $locale = null])

Returns the translation for the given key.
Returns the translation for the given key.

:param array $parameters: Parameters as key/value pairs to populate placeholders in the translation. Note that Symfony has deprecated `transChoice()` in favor of using this method plus defining the key ``%count%`` in ``$parameters``. For example, ``echo $translator->trans('helloworld.number_of_moons', ['%count%' => 1, '%world% => 'Earth']);`` with the translation, ``"helloworld.number_of_moons="{0}%world% has no moons|{1}%world% has one moon|]1,Inf[ %world% has %count% moons"``.
:param string|null $domain: Specific domain to look for the translation key. Defaults to ``messages`` if ``NULL``.
:param string|null $locale: Specific locale to look for the translation key. Defaults to system or user configured locale.
:param array $parameters: Parameters as key/value pairs to populate placeholders in the translation. Note that Symfony has deprecated `transChoice()` in favor of using this method plus defining the key ``%count%`` in ``$parameters``. For example, ``echo $translator->trans('helloworld.number_of_moons', ['%count%' => 1, '%world% => 'Earth']);`` with the translation, ``"helloworld.number_of_moons="{0}%world% has no moons|{1}%world% has one moon|]1,Inf[ %world% has %count% moons"``.
:param string|null $domain: Specific domain to look for the translation key. Defaults to ``messages`` if ``NULL``.
:param string|null $locale: Specific locale to look for the translation key. Defaults to system or user configured locale.

:returns: Returns the translated string if the key is found. Otherwise, an empty string.
:returntype: string
:returns: Returns the translated string if the key is found. Otherwise, an empty string.
:returntype: string

.. php:method:: transConditional(string $preferred, string $alternative[, array $parameters = [], ?string $domain = null, ?string $locale = null])
.. php:method:: transConditional(string $preferred, string $alternative[, array $parameters = [], ?string $domain = null, ?string $locale = null])

Translates the preferred key if it exists and the alternate key if it does not.
Translates the preferred key if it exists and the alternate key if it does not.

:param string $preferred: Preferred translation key.
:param string $alternative: Alternate translation key if the preferred does does not exist.
:param array $parameters: Parameters as key/value pairs to populate placeholders in the translation.
:param string|null $domain: Specific domain to look for the translation key. Defaults to ``messages`` if ``NULL``.
:param string|null $locale: Specific locale to look for the translation key. Defaults to system or user configured locale.
:param string $preferred: Preferred translation key.
:param string $alternative: Alternate translation key if the preferred does does not exist.
:param array $parameters: Parameters as key/value pairs to populate placeholders in the translation.
:param string|null $domain: Specific domain to look for the translation key. Defaults to ``messages`` if ``NULL``.
:param string|null $locale: Specific locale to look for the translation key. Defaults to system or user configured locale.

:returns: Returns the translated string if the key is found. Otherwise, an empty string.
:returntype: string
:returns: Returns the translated string if the key is found. Otherwise, an empty string.
:returntype: string

.. php:method:: hasId(string $id[, ?string $domain = null, ?string $local = null])
.. php:method:: hasId(string $id[, ?string $domain = null, ?string $local = null])

Checks to see if a translation key exists.
Checks to see if a translation key exists.

:param string $id: Translation key. For example, ``mautic.core.empty``.
:param string|null $domain: Specific domain to search. Defaults to ``messages`` if ``NULL``.
:param string|null $locale: Specific locale to search. Defaults to system or user configured locale.
:param string $id: Translation key. For example, ``mautic.core.empty``.
:param string|null $domain: Specific domain to search. Defaults to ``messages`` if ``NULL``.
:param string|null $locale: Specific locale to search. Defaults to system or user configured locale.

:returns: ``TRUE`` if the translation key exists. ``FALSE`` otherwise.
:returntype: boolean
:returns: ``TRUE`` if the translation key exists. ``FALSE`` otherwise.
:returntype: boolean
26 changes: 13 additions & 13 deletions docs/components/ui.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,26 +12,26 @@ Mautic dispatches the Event ``\Mautic\CoreBundle\CoreEvents::VIEW_INJECT_CUSTOM_

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

.. php:method:: public function getLocation()
.. php:method:: public function getLocation()

:return: Requested location for the Button.
:return: Requested location for the Button.

.. php:method:: public function getButtons()
.. php:method:: public function getButtons()

:return: Array of registered Buttons.
:returntype: array
:return: Array of registered Buttons.
:returntype: array

.. php:method:: public function addButtons(array $buttons, $location = null, $route = null)
.. php:method:: public function addButtons(array $buttons, $location = null, $route = null)

:param array[] $buttons: Array of buttons.
:param string $location: Location of the Button to be placed.
:param string $route: Route.
:param array[] $buttons: Array of buttons.
:param string $location: Location of the Button to be placed.
:param string $route: Route.

.. php:method:: public function addButton(array $button, $location = null, $route = null)
.. php:method:: public function addButton(array $button, $location = null, $route = null)

:param array[] $button: :ref:`Details for button<components/ui:Button Array Format>`.
:param string $location: Location of the Button to be placed.
:param string $route: Route.
:param array[] $button: :ref:`Details for button<components/ui:Button Array Format>`.
:param string $location: Location of the Button to be placed.
:param string $route: Route.

A Plugin can inject the Buttons into five places in Mautic's UI.

Expand Down
2 changes: 1 addition & 1 deletion docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,11 +45,11 @@
# ones.
extensions = [
'xref',
'phpdomain',
'code_samples_ext',
'sphinx_rtd_theme',
'sphinx.ext.viewcode',
'sphinx.ext.autosectionlabel',
'sphinxcontrib.phpdomain',
]

# Add any paths that contain templates here, relative to this directory.
Expand Down
20 changes: 10 additions & 10 deletions docs/plugins/config.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,22 +197,22 @@

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

.. php:method:: getType()
.. php:method:: getType()

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

Check failure on line 202 in docs/plugins/config.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Vale.Terms] Use 'Plugins' instead of 'plugins'.

Raw Output:
{"message": "[Vale.Terms] Use 'Plugins' instead of 'plugins'.", "location": {"path": "docs/plugins/config.rst", "range": {"start": {"line": 202, "column": 42}}}, "severity": "ERROR"}

Check warning on line 202 in docs/plugins/config.rst

View workflow job for this annotation

GitHub Actions / prose 

[vale] reported by reviewdog 🐶
[Mautic.FeatureList] Is this referring to a Mautic feature? If so, use 'Plugins' instead of 'plugins'.

Raw Output:
{"message": "[Mautic.FeatureList] Is this referring to a Mautic feature? If so, use 'Plugins' instead of 'plugins'.", "location": {"path": "docs/plugins/config.rst", "range": {"start": {"line": 202, "column": 42}}}, "severity": "INFO"}
:returntype: string

.. php:method:: getCollection()
.. php:method:: getCollection()

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

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

Load custom routes through a resource file such as yaml or XML.
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
:param string $path: Path to the resource file. For example, ``@FMElfinderBundle/Resources/config/routing.yaml``.
:returntype: void

Debugging routes
================
Expand Down
Loading
Loading