.. _sardana-reference:

=========
Reference
=========

Precise lookup material for Sardana: the command line tools, catalogs of
macros and environment variables, the plugin and library APIs, the Tango
interface and configuration settings, migration guides and design records.
For learning material see the :ref:`tutorials <sardana-tutorials>`, for
recipes the :ref:`how-to guides <sardana-how-to>`, for background the
:ref:`explanations <sardana-explanation>`, and for release notes and built
documentation of other versions the
:ref:`news and releases <sardana-news>` section.

Command line tools
------------------

* :doc:`cli` -- the executables installed by Sardana and the ``sardanactl``
  subcommands.

.. toctree::
    :hidden:
    :maxdepth: 1

    Command line tools <cli>

Macros
------

* :doc:`macro_catalog` -- catalog of the standard macros shipped with Sardana.
* :doc:`api/api_macro` -- the macro API: classes, decorators and parameter types
  used to write and run macros.

.. toctree::
    :hidden:
    :maxdepth: 1

    Macro catalog <macro_catalog>
    Macro API <api/api_macro>

Plugin APIs
-----------

* :doc:`api/api_controller` -- the controller plugin API: base classes,
  axis/controller parameters and data types.
* :doc:`recorder_api` -- the recorder plugin API: base classes for writing
  scan data recorders.

.. toctree::
    :hidden:
    :maxdepth: 1

    Controller API <api/api_controller>
    Recorder API <recorder_api>

Element APIs
------------

Attribute-by-attribute reference of each Sardana element type:

* :doc:`api/api_motor` -- motor element (state, position, velocity, limits...).
* :doc:`api/api_IOR` -- input/output register element.
* :doc:`api/api_countertimer` -- counter/timer experiment channel.
* :doc:`api/api_0D` -- 0D experiment channel.
* :doc:`api/api_1D` -- 1D experiment channel.
* :doc:`api/api_2D` -- 2D experiment channel.
* :doc:`api/api_triggergate` -- trigger/gate synchronizer element.
* :doc:`api/api_pseudomotor` -- pseudo motor element.
* :doc:`api/api_pseudocounter` -- pseudo counter element.
* :doc:`api/api_measurementgroup` -- measurement group element.
* :doc:`api/api_macroserver` -- MacroServer and Door elements.
* :doc:`api/api_pool` -- Device Pool element.

.. toctree::
    :hidden:
    :maxdepth: 1

    Motor API <api/api_motor>
    I/O register API <api/api_IOR>
    Counter/timer API <api/api_countertimer>
    0D experiment channel API <api/api_0D>
    1D experiment channel API <api/api_1D>
    2D experiment channel API <api/api_2D>
    Trigger/gate API <api/api_triggergate>
    Pseudo motor API <api/api_pseudomotor>
    Pseudo counter API <api/api_pseudocounter>
    Measurement group API <api/api_measurementgroup>
    MacroServer API <api/api_macroserver>
    Pool API <api/api_pool>

Python library
--------------

* :doc:`api/api_sardana` -- curated overview of the public Python APIs.
* :doc:`api/sardana/sardana` -- exhaustive :mod:`sardana` package and module
  reference, browsable directly.
* :doc:`api/sardana/taurus/core/tango/sardana` -- Sardana-Taurus model API
  (Taurus extensions for Sardana devices).
* :doc:`api/sardana/taurus/qt/qtcore/tango/sardana` -- Sardana-Taurus Qt
  model API.
* :doc:`api/api_test` -- test framework utilities and base classes.

.. toctree::
    :hidden:
    :maxdepth: 1

    Python API overview <api/api_sardana>
    Python package reference <api/sardana/sardana>
    Sardana-Taurus model API <api/sardana/taurus/core/tango/sardana>
    Sardana-Taurus Qt model API <api/sardana/taurus/qt/qtcore/tango/sardana>
    Test API <api/api_test>

Tango interface
---------------

* :doc:`api/tango_device_pool` -- reference of the Sardana Tango device
  classes: their attributes, commands and properties.

.. toctree::
    :hidden:
    :maxdepth: 1

    Tango objects <api/tango_device_pool>

Configuration
-------------

* :doc:`configuration/index` -- configuration reference: Sardana custom
  settings and pointers to the Tango device properties.
* :doc:`environment_variable_catalog` -- catalog of the environment variables
  recognized by Sardana macros and scans.

.. toctree::
    :hidden:
    :maxdepth: 1

    Configuration <configuration/index>
    Environment variable catalog <environment_variable_catalog>

Project records
---------------

* :doc:`migration/index` -- how to migrate Sardana systems and plugins
  between API versions.
* :doc:`sep/index` -- Sardana Enhancement Proposals (design documents).

.. toctree::
    :hidden:
    :maxdepth: 1

    Migration guides <migration/index>
    SEPs <sep/index>