Adds python API reference

.gitignore

@@ -13,3 +13,9 @@ build/
 source/.buildinfo
 source/*.inv
 source/_outputs/
+
+# direnv
+.envrc
+
+# autogenerated documentation
+source/reference/python/RATapi.*

requirements.txt

@@ -4,3 +4,5 @@ pydata-sphinx-theme==0.15.2
 sphinx_design==0.6.0
 sphinx-copybutton==0.5.2
 RATapi==0.0.0.dev4
+autodoc_pydantic==2.2.0
+enum-tools[sphinx]==0.12.0

source/conf.py

@@ -37,7 +37,7 @@
 # add extensions path for snippets
 sys.path.append(os.path.abspath("./_ext"))
 
-extensions = ['sphinxcontrib.matlab', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx_design', 'sphinx_copybutton', 'snippets']
+extensions = ['sphinxcontrib.matlab', 'sphinx.ext.napoleon', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinxcontrib.autodoc_pydantic', 'sphinx_design', 'sphinx_copybutton', 'snippets', 'enum_tools.autoenum']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -78,4 +78,27 @@
 }
 
 copybutton_prompt_text = r">>> |>> "
-copybutton_prompt_is_regexp = True
+copybutton_prompt_is_regexp = True
+
+autodoc_typehints = "description"
+
+### autodoc_pydantic settings
+# hide JSON schemas by default
+autodoc_pydantic_model_show_json = False
+autodoc_pydantic_settings_show_json = False
+
+# don't show validators or config 
+autodoc_pydantic_field_list_validators = False
+autodoc_pydantic_model_show_config_summary = False
+autodoc_pydantic_model_show_validator_summary = False
+autodoc_pydantic_model_show_validator_members = False
+
+# hide parameter list in class signature
+autodoc_pydantic_settings_hide_paramlist = True
+
+# do not show list of fields if they do not have docstrings
+# (e.g. for models we use the main docstring)
+autodoc_pydantic_model_undoc_members = False
+
+# get field documentation from field docstrings
+autodoc_pydantic_field_doc_policy = "docstring"

source/index.rst

@@ -55,6 +55,7 @@ RAT contains a number of improvements over legacy RasCAL, including:
         Learn more by diving into the RAT reference:
 
         * :ref:`matlab_api`: Detailed information about all of RAT's MATLAB API.
+        * :ref:`python_api`: Detailed information about the RAT Python API.
 
 
     .. grid-item-card::
@@ -77,4 +78,5 @@ RAT contains a number of improvements over legacy RasCAL, including:
    install
    guide
    reference/matlab/index
+   reference/python/index
 

source/reference/python/classlist.rst

@@ -0,0 +1,4 @@
+ClassList
+---------
+
+.. autoclass:: RATapi.ClassList

source/reference/python/controls.rst

@@ -0,0 +1,9 @@
+Controls
+--------
+
+The ``Controls`` class details control parameters for the RAT run. Note that many of these are
+specific to certain procedures: the relevant procedure is listed in square brackets before the
+field description.
+
+.. autopydantic_model:: RATapi.Controls
+   :members: 

source/reference/python/core.rst

@@ -0,0 +1,8 @@
+RAT Core 
+--------
+
+This module contains the `Pybind11 <https://pybind11.readthedocs.io/en/stable/index.html>`_ objects 
+which are used to interface with RAT's C++ code. 
+
+.. automodule:: RATapi.rat_core
+   :members:

source/reference/python/enums.rst

@@ -0,0 +1,9 @@
+Enums 
+-----
+
+This utility module (found in ``RATapi.utils.enums``) contains the Enum objects
+which are used under the hood to represent arguments given as string options,
+such as those for control parameters or background types.
+
+.. automodule:: RATapi.utils.enums
+   :members:

source/reference/python/events.rst

@@ -0,0 +1,5 @@
+Events
+------
+
+.. automodule:: RATapi.events
+   :members:

source/reference/python/examples.rst

@@ -0,0 +1,5 @@
+Examples 
+--------
+
+.. automodule:: RATapi.examples
+   :members:

source/reference/python/index.rst

@@ -0,0 +1,32 @@
+.. _python_api:
+
+Python API Reference
+--------------------
+
+User API
+^^^^^^^^
+
+.. toctree::
+    :maxdepth: 2
+
+    run
+    project
+    controls
+    classlist
+    models
+    events
+    examples
+    plotting
+    enums
+
+
+Developer API
+^^^^^^^^^^^^^
+
+.. toctree::
+   :maxdepth: 2
+
+   core
+   inputs
+   outputs
+   wrappers

source/reference/python/inputs.rst

@@ -0,0 +1,8 @@
+Inputs 
+------
+
+This module contains the objects used to organise input data to RAT to be fed
+into the C++ module.
+
+.. automodule:: RATapi.inputs
+   :members:

source/reference/python/models.rst

@@ -0,0 +1,7 @@
+Models
+------
+
+.. automodule:: RATapi.models
+   :members:
+   :inherited-members: RATModel
+   :exclude-members: RATModel, Signal

source/reference/python/outputs.rst

@@ -0,0 +1,8 @@
+Outputs 
+-------
+
+This module contains the Results objects and the relevant objects to retrieve
+results data from the C++ module.
+
+.. automodule:: RATapi.outputs
+   :members:

source/reference/python/plotting.rst

@@ -0,0 +1,10 @@
+Plotting
+--------
+
+Plotting functionality for RAT results objects is available through the ``RATapi.utils.plotting`` module.
+
+.. note: plot_bayes is currently excluded because its docstring is not valid RST!
+
+.. automodule:: RATapi.utils.plotting
+   :members:
+   :exclude-members: plot_errorbars, plot_ref_sld_helper, assert_bayesian, name_to_index, panel_plot_helper, plot_bayes 

source/reference/python/project.rst

@@ -0,0 +1,6 @@
+Project
+-------
+
+.. autopydantic_model:: RATapi.Project
+   :members:
+

source/reference/python/run.rst

@@ -0,0 +1,6 @@
+Run
+---
+
+The core function to run RAT.
+
+.. autofunction:: RATapi.run

source/reference/python/wrappers.rst

@@ -0,0 +1,8 @@
+Wrappers 
+--------
+
+This module contains the wrappers for interfacing with MATLAB custom functions,
+such as those for custom layers models or function backgrounds.
+
+.. automodule:: RATapi.wrappers
+   :members: