Add documentation for Python API

docs/convert.rst

@@ -0,0 +1,37 @@
+.. _convert:
+
+==========
+Python API
+==========
+
+otoole also provides a Python API to access all the features available from the command line tool.
+
+Converting between formats
+--------------------------
+
+``otoole`` currently supports conversion between the following formats:
+
+- Excel
+- A folder of CSV files
+- GNU MathProg datafile
+
+>>> from otoole import convert
+>>> convert('my_model.yaml', 'excel', 'csv', 'my_model.xlsx', 'my_model_csvs')
+
+See :py:func:`otoole.convert.convert` for more details
+
+Converting solver results to a folder of CSV files
+--------------------------------------------------
+
+The ``convert_results`` function creates a folder of CSV result files from a CBC_, CLP_,
+Gurobi_ or CPLEX_ solution file::
+
+>>> from otoole import convert_results
+>>> convert_results('my_model.yaml', 'cbc', 'csv', 'my_model.sol', 'my_model_csvs', input_datafile='my_model.dat')
+
+See :func:`otoole.convert.convert_results` for more details
+
+.. _CBC: https://github.com/coin-or/Cbc
+.. _CLP: https://github.com/coin-or/Clp
+.. _CPLEX: https://www.ibm.com/products/ilog-cplex-optimization-studio/cplex-optimizer
+.. _Gurobi: https://www.gurobi.com/

docs/index.rst

@@ -5,8 +5,8 @@ Welcome to the documentation of ``otoole``!
 ===========================================
 
 **otoole**, or **O**\ SeMOSYS **tool**\ s for **e**\ nergy work, is a Python package
-which provides a command-line interface for users of OSeMOSYS. The aim of the package is
-to provide commonly used pre- and post-processing steps when  working with OSeMOSYS models.
+which provides a command-line interface and Python API for users of OSeMOSYS. The aim of the
+package is to provide commonly used pre- and post-processing steps when working with OSeMOSYS models.
 Specifically, ``otoole`` allows the user to convert between data formats, process solutions,
 and visualise the reference energy system.
 
@@ -28,6 +28,7 @@ Contents
    Core Functionality <functionality>
    Data Formats <data>
    Examples <examples>
+   Python API <convert>
    Contributing <contributing>
    License <license>
    Authors <authors>

src/otoole/convert.py

@@ -36,14 +36,29 @@ def convert_results(
     Arguments
     ---------
     config : str
+        Path to config file
+    from_format : str
+        Available options are 'cbc', 'cplex' and 'gurobi'
+    to_format : str
+        Available options are 'csv'
+    from_path : str
+        Path to cbc, cplex or gurobi solution file
+    to_path : str
+        Path to destination folder
     input_datapackage : str
+        Path to folder containing datapackage.json
     input_csvs : str
+        Path to folder containing CSVs
     input_datafile : str
-    to_path : str
-    from_path : str
-    from_format : str
-    to_format : str
+        Path to datafile
     write_defaults : str
+        Write default values to CSVs
+
+    Returns
+    -------
+    bool
+        True if conversion was successful, False otherwise
+
     """
     msg = "Conversion from {} to {} is not yet implemented".format(
         from_format, to_format
@@ -124,12 +139,14 @@ def convert(
     from_path : str
         Path to destination file (if datafile or excel) or folder (csv or datapackage)
     write_defaults: bool, default: False
+        Write default values to CSVs
     keep_whitespace: bool, default: False
+        Keep whitespace in CSVs
 
     Returns
     -------
     bool
-        True if conversion was successful
+        True if conversion was successful, False otherwise
     """
 
     msg = "Conversion from {} to {} is not yet implemented".format(
@@ -144,8 +161,6 @@ def convert(
         logger.info("Validating config from {}".format(config))
         validate_config(user_config)
 
-    # set read strategy
-
     keep_whitespace = True if keep_whitespace else False
 
     if from_format == "datafile":