Sphinx Documentation
################################

The Robusta documentation is written using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.

We wrote a custom Sphinx extension named `autorobusta <https://github.com/robusta-dev/robusta/blob/master/docs/_ext/autorobusta.py>`_ to generate docs for Robusta actions.

For example, we can generate docs for the builtin ``logs_enricher`` action as follows:

.. code-block::

    .. robusta-action:: playbooks.robusta_playbooks.alerts_integration.logs_enricher

You can see the output in the Robusta documentation itself for the :ref:`logs_enricher` action.

The Sphinx extension reads the action's source code (in this case, the
`logs_enricher source code <https://github.com/robusta-dev/robusta/blob/990814c9e47f5cabc24fbb06794b4dbaa62fb958/playbooks/robusta_playbooks/alerts_integration.py#L215>`_
source code) and uses that to generate the docs in a standard format. You can modify the generated documentation in two ways:

1. By annotating your source code
2. By passing parameters to the Sphinx directive.

.. warning::

    The documentation process isn't completely automated yet!

    After adding an action to Robusta, you should update the relevant `actions page <https://github.com/robusta-dev/robusta/tree/master/docs/catalog/actions>`_
    and add one line with a ``robusta-action`` directive for your new action. From there, everything else is automated.

Annotating your source code
----------------------------

.. warning::

    Sorry, we haven't gotten around to documenting this part yet! Feel free to open a PR to fix that.

Parameters
----------

You can customize the Sphinx output by passing parameters to the directives.

Recommending a trigger
~~~~~~~~~~~~~~~~~~~~~~~~~~

You can explicitly override the trigger used in autogenerated examples by passing a second parameter to the ``robusta-action`` directive.

For example:

.. code-block::

    .. robusta-action:: playbooks.robusta_playbooks.grafana_enrichment.add_deployment_lines_to_grafana on_deployment_update

You can further customize it by adding parameters to the autogenerated trigger:

.. code-block::

    .. robusta-action:: playbooks.robusta_playbooks.bash_enrichments.pod_bash_enricher
        :trigger-params: {"alert_name": "ExampleLowDiskAlert"}



Manually-triggered action
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mark an action as a "manually triggered action" to prevent an "Example Config" from being shown:

.. code-block::

    .. robusta-action:: playbooks.robusta_playbooks.prometheus_simulation.prometheus_alert
        :manual-trigger-only:

See :ref:`prometheus_alert` for an example.