Adds python API reference (#25)

* added python API reference

* added autodoc-pydantic to requirements

* better docstrings via napoleon

* added explanatory note for controls docstrings

* added plotting page

* removed plot_bayes due to docstring

* review fixes

* review fixes

Author: alexhroom

.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

@@ -39,7 +39,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']
@@ -80,4 +80,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: