docs: describe public api in front-page of API docs (#4536)

* docs: describe public api in front-page of API docs

* docs: add set_logging_level to docs

* docs: move public api description to userguide

* fix doctest warnings

* fix reference

* edit parameters for clarity

---------

Co-authored-by: Eric G. Kratz <[email protected]>

docs/source/api/index.rst

@@ -9,10 +9,10 @@ API documentation
 :Release: |version|
 :Date: |today|
 
-This reference manual details functions, modules, and objects
-included in PyBaMM, describing what they are and what they do.
+This reference manual details the classes, functions, modules, and objects included in PyBaMM, describing what they are and what they do.
 For a high-level introduction to PyBaMM, see the :ref:`user guide <user_guide>` and the :ref:`examples <pybamm_examples>`.
 
+
 .. toctree::
    :maxdepth: 2
 

docs/source/api/util.rst

@@ -19,3 +19,5 @@ Utility functions
 .. autofunction:: pybamm.has_jax
 
 .. autofunction:: pybamm.is_jax_compatible
+
+.. autofunction:: pybamm.set_logging_level

docs/source/user_guide/fundamentals/public_api.rst

@@ -0,0 +1,74 @@
+----------
+Public API
+----------
+
+.. module:: pybamm
+    :noindex:
+
+PyBaMM is a Python package for mathematical modelling and simulation of battery systems. The main classes and functions that are intended to be used by the user are described in this document.
+For a more detailed description of the classes and methods, see the :doc:`API reference </source/api/index>`.
+
+Available PyBaMM models
+-----------------------
+
+PyBaMM includes a number of pre-implemented models, which can be used as they are or modified to suit your needs. The main models are:
+
+- :class:`lithium_ion.SPM`: Single Particle Model
+- :class:`lithium_ion.SPMe`: Single Particle Model with Electrolyte
+- :class:`lithium_ion.DFN`: Doyle-Fuller-Newman
+
+The behaviour of the models can be modified by passing in an :class:`BatteryModelOptions` object when creating the model.
+
+Simulations
+-----------
+
+:class:`Simulation` is a class that automates the process of setting up a model and solving it, and acts as the highest-level API to PyBaMM.
+Pass at least a :class:`BaseModel` object, and optionally the experiment, solver, parameter values, and geometry objects described below to the :class:`Simulation` object.
+Any of these optional arguments not provided will be supplied by the defaults specified in the model.
+
+Parameters
+----------
+
+PyBaMM models are parameterised by a set of parameters, which are stored in a :class:`ParameterValues` object. This object acts like a Python dictionary with a few extra PyBaMM specific features and methods.
+Parameters in a model are represented as either :class:`Parameter` objects or :class:`FunctionParameter` objects, and the values in the :class:`ParameterValues` object replace these objects in the model before it is solved.
+The values in the :class:`ParameterValues` object can be scalars, Python functions or expressions of type :class:`Symbol`.
+
+Experiments
+-----------
+
+An :class:`Experiment` object represents an experimental protocol that can be used to simulate the behaviour of a battery. The particular protocol can be provided as a Python string, or as a sequences of
+:class:`step.BaseStep` objects.
+
+Solvers
+-------
+
+The two main solvers in PyBaMM are the :class:`CasadiSolver` and the :class:`IDAKLUSolver`. Both are wrappers around the Sundials suite of solvers, but the :class:`CasadiSolver` uses the CasADi library
+whereas the :class:`IDAKLUSolver` is PyBaMM specific. Both solvers have many options that can be set to control the solver behaviour, see the documentation for each solver for more details.
+
+When a model is solved, the solution is returned as a :class:`Solution` object.
+
+Plotting
+--------
+
+A solution object can be plotted using the :meth:`Solution.plot` or :meth:`Simulation.plot` methods, which returns a :class:`QuickPlot` object.
+Note that the arguments to the plotting methods of both classes are the same as :class:`QuickPlot`.
+
+Other plotting functions are the :func:`plot_voltage_components` and :func:`plot_summary_variables` functions, which correspond to the similarly named methods of the :class:`Solution` and :class:`Simulation` classes.
+
+Writing PyBaMM models
+---------------------
+
+Each PyBaMM model, and the custom models written by users, are written as a set of expressions that describe the model. Each of the expressions is a subclass of the :class:`Symbol` class, which represents a mathematical expression.
+
+If you wish to create a custom model, you can use the :class:`BaseModel` class as a starting point.
+
+
+Discretisation
+--------------
+
+Each PyBaMM model contains continuous operators that must be discretised before they can be solved. This is done using a :class:`Discretisation` object, which takes a :class:`Mesh` object and a dictionary of :class:`SpatialMethod` objects.
+
+Logging
+-------
+
+PyBaMM uses the Python logging module to log messages at different levels of severity. Use the :func:`pybamm.set_logging_level` function to set the logging level for PyBaMM.

docs/source/user_guide/index.md

@@ -22,6 +22,7 @@ maxdepth: 2
 ---
 fundamentals/index
 fundamentals/battery_models
+fundamentals/public_api
 ```
 
 ```{toctree}

src/pybamm/logger.py

@@ -24,6 +24,17 @@ def func(self, message, *args, **kws):
 
 
 def set_logging_level(level):
+    """
+    Set the logging level for PyBaMM
+
+    Parameters
+    ----------
+
+    level: str
+        The logging level to set. Should be one of 'DEBUG', 'INFO', 'WARNING',
+        'ERROR', 'CRITICAL'
+
+    """
     logger.setLevel(level)