doc: add jupyter notebook with oetc example use (#490)

* doc: add jupyter notebook with oetc example use

* doc: configure nbsphinx execution settings

Enable auto-execution with inline backend configuration
Exclude OETC notebook from automatic execution

* doc: update styles and address warnings

* refac: jupyter notebook format

Author: FabianHofmann

doc/Makefile

@@ -12,7 +12,12 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help clean Makefile
+
+# Clean target that removes build directory
+clean:
+	@echo "Removing build directory..."
+	rm -rf "$(BUILDDIR)"
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

doc/api.rst

@@ -121,21 +121,32 @@ IO functions
     model.Model.to_netcdf
     io.read_netcdf
 
+Solver utilities
+=================
+
+.. autosummary::
+    :toctree: generated/
+
+    solvers.available_solvers
+    solvers.quadratic_solvers
+    solvers.Solver
+
+
 Solvers
-========
+=======
 
 .. autosummary::
     :toctree: generated/
 
-    solvers.run_cbc
-    solvers.run_glpk
-    solvers.run_highs
-    solvers.run_cplex
-    solvers.run_gurobi
-    solvers.run_xpress
-    solvers.run_mosek
-    solvers.run_mindopt
-    solvers.run_copt
+    solvers.CBC
+    solvers.Cplex
+    solvers.GLPK
+    solvers.Gurobi
+    solvers.Highs
+    solvers.Mosek
+    solvers.SCIP
+    solvers.Xpress
+
 
 Solving
 ========

doc/conf.py

@@ -90,7 +90,15 @@
 
 """
 
-nbsphinx_allow_errors = False
+nbsphinx_allow_errors = True
+nbsphinx_execute = "auto"
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'svg', 'pdf'}",
+    "--InlineBackend.rc={'figure.dpi': 96}",
+]
+
+# Exclude notebooks that require credentials or special setup
+nbsphinx_execute_never = ["**/solve-on-oetc*"]
 
 # -- Options for HTML output -------------------------------------------------
 

doc/index.rst

@@ -114,6 +114,7 @@ This package is published under MIT license.
    transport-tutorial
    infeasible-model
    solve-on-remote
+   solve-on-oetc
    migrating-from-pyomo
    gurobi-double-logging
 

doc/release_notes.rst

@@ -2,7 +2,6 @@ Release Notes
 =============
 
 Upcoming Version
-----------------
 
 * Replace pandas-based LP file writing with polars implementation for significantly improved performance on large models
 * Consolidate "lp" and "lp-polars" io_api options - both now use the optimized polars backend
@@ -37,7 +36,7 @@ Version 0.5.4
 **Bug Fixes**
 
 * Remove default highs log file when `log_fn=None` and `io_api="direct"`. This caused `log_file` in
-`solver_options` to be ignored.
+  `solver_options` to be ignored.
 * Fix the parsing of solutions returned by the CBC solver when setting a MIP duality
   gap tolerance.
 * Improve the mapping of termination conditions for the SCIP solver
@@ -65,8 +64,8 @@ Version 0.5.2
 **Bug Fixes**
 
 * Fix the multiplication with of zero dimensional numpy arrays with linopy objects.
-This is mainly affecting operations where single numerical items from  pandas objects
-are selected and used for multiplication.
+  This is mainly affecting operations where single numerical items from  pandas objects
+  are selected and used for multiplication.
 
 Version 0.5.1
 --------------
@@ -199,7 +198,7 @@ Version 0.3.9
 
 * The constraint assignment with a `LinearExpression` and a constant value when using the pattern `model.add_constraints(lhs_with_constant, sign, rhs)` was fixed. Before, the constant value was not added to the right-hand-side properly which led to the wrong constraint behavior. This is fixed now.
 
-* `nan`s in constants is now handled more consistently. These are ignored when in the addition of expressions (effectively filled by zero). In a future version, this might change to align the propagation of `nan`s with tools like numpy/pandas/xarray.
+* ``nan`` s in constants is now handled more consistently. These are ignored when in the addition of expressions (effectively filled by zero). In a future version, this might change to align the propagation of ``nan`` s with tools like numpy/pandas/xarray.
 
 * Up to now the `rhs` argument in the `add_constraints` function was not supporting an expression as an input type. This is now added.
 

doc/solve-on-oetc.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../examples/solve-on-oetc.ipynb"
+}

examples/creating-expressions.ipynb

@@ -160,10 +160,7 @@
    "cell_type": "markdown",
    "id": "f7578221",
    "metadata": {},
-   "source": [
-    ".. important::\n",
-    "   When combining variables or expression with dimensions of the same name and size, the first object will determine the coordinates of the resulting expression. For example: "
-   ]
+   "source": ".. important::\n\n\tWhen combining variables or expression with dimensions of the same name and size, the first object will determine the coordinates of the resulting expression. For example:"
   },
   {
    "cell_type": "code",

examples/creating-variables.ipynb

@@ -467,13 +467,7 @@
    "cell_type": "markdown",
    "id": "77e264e2",
    "metadata": {},
-   "source": [
-    ".. important::\n",
-    "\n",
-    "    **New in version 0.3.6**\n",
-    "\n",
-    "    As pandas objects always have indexes, the `coords` argument is not required and is ignored is passed. Before, it was used to overwrite the indexes of the pandas objects. A warning is raised if `coords` is passed and if these are not aligned with the pandas object. "
-   ]
+   "source": ".. important::\n\n    **New in version 0.3.6**\n\n    As pandas objects always have indexes, the `coords` argument is not required and is ignored is passed. Before, it was used to overwrite the indexes of the pandas objects. A warning is raised if `coords` is passed and if these are not aligned with the pandas object."
   },
   {
    "cell_type": "code",