oemof · p-snft · Aug 15, 2023 · Jul 6, 2023 · Jul 6, 2023 · Jul 6, 2023
diff --git a/.github/workflows/tox_checks.yml b/.github/workflows/tox_checks.yml
@@ -25,6 +25,8 @@ jobs:
           - docs
 
     steps:
+      - name: Update package list
+        run: sudo apt update
       - name: Install LaTeX
         run: sudo apt install dvipng rubber texlive-latex-extra
       - name: Git clone

diff --git a/README.rst b/README.rst
@@ -100,23 +100,22 @@ Introduction
 
 The oemof.solph package is part of the
 `Open energy modelling framework (oemof) <https://github.com/oemof/oemof>`_.
-This an organisational framework to bundle tools for energy (system) modelling.
+This is an organisational framework to bundle tools for energy (system) modelling.
 oemof-solph is a model generator for energy system modelling and optimisation.
 
-The ``oemof.solph`` package is very often called just ``oemof`` as it was part of the
-oemof meta package. Now you need to install ``oemof.solph`` instead of ``oemof``, but
-everything else is still the same.
-(Note: Since the oemof package refers to legacy versions before v0.4,
-it is not possible to install both, oemof and oemof.solph, at the same time.
-Just use ``pip install oemof.solph``.)
+The package ``oemof.solph`` is very often called just ``oemof``.
+This is because installing the ``oemof`` meta package was once the best way to get ``oemof.solph``.
+Notice that you should prefeably install ``oemof.solph`` instead of ``oemof``
+if you want to use ``solph``.
+
 
 Everybody is welcome to use and/or develop oemof.solph.
 Read our `contribution <https://oemof.readthedocs.io/en/latest/contributing.html>`_ section.
 
 Contribution is already possible on a low level by simply fixing typos in
 oemof's documentation or rephrasing sections which are unclear.
 If you want to support us that way please fork the oemof-solph repository to your own
-github account and make changes as described in the `github guidelines <https://docs.github.com/en/get-started/quickstart/hello-world>`_
+GitHub account and make changes as described in the `github guidelines <https://docs.github.com/en/get-started/quickstart/hello-world>`_
 
 If you have questions regarding the use of oemof including oemof.solph you can visit the openmod forum (`tag oemof <https://forum.openmod-initiative.org/tags/c/qa/oemof>`_ or `tag oemof-solph <https://forum.openmod-initiative.org/tags/c/qa/oemof-solph>`_) and open a new thread if your questions hasn't been already answered.
 
@@ -135,20 +134,26 @@ The `oemof.solph documentation <https://oemof-solph.readthedocs.io/>`_ is powere
 Installation
 ============
 
-If you have a working Python3 environment, use pypi to install the latest version of oemof.solph. Python >= 3.8 is recommended. Lower versions may work but are not tested.
 
+If you have a working Python installation, use pypi to install the latest version of oemof.solph.
+Python >= 3.8 is recommended. Lower versions may work but are not tested.
+
+We highly recommend to use virtual environments.
+Please refer to the documentation of your Python distribution (e.g. Anaconda,
+Micromamba, or the version of Python that came with your Linux installation)
+to learn how to set up and use virtual environments.
 
 ::
 
-    pip install oemof.solph
+    (venv) pip install oemof.solph
 
 If you want to use the latest features, you might want to install the **developer version**. The developer version is not recommended for productive use::
 
-    pip install https://github.com/oemof/oemof-solph/archive/dev.zip
+    (venv) pip install https://github.com/oemof/oemof-solph/archive/dev.zip
 
 
 For running an oemof-solph optimisation model, you need to install a solver.
-Following you will find guidelines for the installation process for different operation systems.
+Following you will find guidelines for the installation process for different operating systems.
 
 .. _windows_solver_label:
 .. _linux_solver_label:
@@ -157,7 +162,7 @@ Installing a solver
 -------------------
 
 There are various commercial and open-source solvers that can be used with oemof.
-There are two common OpenSource solvers available (CBC, GLPK), while oemof recommends CBC (Coin-or branch and cut).
+There are two common Open-Source solvers available (CBC, GLPK), while oemof recommends CBC (Coin-or branch and cut).
 But sometimes its worth comparing the results of different solvers.
 Other commercial solvers like Gurobi or Cplex can be used as well.
 Have a look at the `pyomo docs <https://pyomo.readthedocs.io/en/stable/solving_pyomo_models.html#supported-solvers>`_ to learn about which solvers are supported.
@@ -192,12 +197,12 @@ If you install the CBC solver via brew (highly recommended), it should work with
 
 **conda**
 
-Provided you are using a Linux or MacOS, the CBC-solver can also be installed in a `conda` environment. Please note, that it is highly recomended to `use pip after conda <https://www.anaconda.com/blog/using-pip-in-a-conda-environment>`_, so:
+Provided you are using a Linux or MacOS, the CBC-solver can also be installed in a `conda` environment. Please note, that it is highly recommended to `use pip after conda <https://www.anaconda.com/blog/using-pip-in-a-conda-environment>`_, so:
 
 .. code:: console
 
-    conda install -c conda-forge coincbc
-    pip install oemof.solph
+    (venv) conda install -c conda-forge coincbc
+    (venv) pip install oemof.solph
 
 
 .. _check_installation_label:
@@ -210,7 +215,7 @@ in your virtual environment:
 
 .. code:: console
 
-  oemof_installation_test
+  (venv) oemof_installation_test
 
 If the installation was successful, you will receive something like this:
 
@@ -253,15 +258,16 @@ To allow citing specific versions, we use the zenodo project to get a DOI for ea
 Examples
 ========
 
-The linkage of specific modules of the various packages is called an
-application (app) and depicts for example a concrete energy system model.
-You can find a large variety of helpful examples in `oemof's example repository <https://github.com/oemof/oemof-examples>`_ on github to download or clone.
-The examples show optimisations of different energy systems and are supposed
+The combination of specific modules (often including other packages) is called an
+application (app). For example, it can depict a concrete energy system model.
+You can find a large variety of helpful examples in the documentstion.
+The examples show optimisation of different energy systems and are supposed
 to help new users to understand the framework's structure.
 There is some elaboration on the examples in the respective repository.
 The repository has sections for each major release.
 
-You are welcome to contribute your own examples via a `pull request <https://github.com/oemof/oemof-examples/pulls>`_ or by sending us an e-mail (see `here <https://oemof.org/contact/>`_ for contact information).
+You are welcome to contribute your own examples via a `pull request <https://github.com/oemof/oemof-solph/pulls>`_
+or by e-mailing us (see `here <https://oemof.org/contact/>`_ for contact information).
 
 License
 =======

diff --git a/docs/conf.py b/docs/conf.py
@@ -27,6 +27,8 @@ def setup(app):
     "sphinx.ext.napoleon",
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+    "sphinx_design",
 ]
 source_suffix = ".rst"
 master_doc = "index"

diff --git a/docs/examples/activity_costs.rst b/docs/examples/activity_costs.rst
@@ -0,0 +1,7 @@
+Activity costs
+--------------
+
+Costs for operation a boiler
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: activity_costs.activity_costs
diff --git a/docs/examples/basic_example.rst b/docs/examples/basic_example.rst
@@ -0,0 +1,7 @@
+Basic example
+-------------
+
+Using standard oemof-solph components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: basic_example.basic_example
diff --git a/docs/examples/cellular.rst b/docs/examples/cellular.rst
@@ -0,0 +1,7 @@
+Cellular energy system
+----------------------
+
+Building your system from smaller cells
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: cellular.cellular
diff --git a/docs/examples/custom_constraints.rst b/docs/examples/custom_constraints.rst
@@ -0,0 +1,15 @@
+.. _custom_constraints_label:
+
+Custom constraints
+------------------
+
+Custom-made shared limit for Flows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: flexible_modelling.add_constraints
+
+
+Charge-rate depending on state-of-charge
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: flexible_modelling.saturating_storage
diff --git a/docs/examples/electrical.lopf.rst b/docs/examples/electrical.lopf.rst
@@ -0,0 +1,7 @@
+Linear optimal power flow (lopf)
+--------------------------------
+
+Three-Bus system
+~~~~~~~~~~~~~~~~
+
+.. automodule:: electrical.lopf
diff --git a/docs/examples/electrical.transshipment.rst b/docs/examples/electrical.transshipment.rst
@@ -0,0 +1,7 @@
+Transshipment
+-------------
+
+Using the link component
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: electrical.transshipment
diff --git a/docs/examples/emission_constraint.rst b/docs/examples/emission_constraint.rst
@@ -0,0 +1,7 @@
+Emission constraint
+-------------------
+
+Limiting CO2 emissions
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: emission_constraint.emission_constraint
diff --git a/docs/examples/excel_reader.rst b/docs/examples/excel_reader.rst
@@ -0,0 +1,9 @@
+.. _excel_reader_example_label:
+
+Spreadsheet (Excel) Reader
+--------------------------
+
+Generating a model from excel
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: excel_reader.dispatch
diff --git a/docs/examples/flow_count_limit.rst b/docs/examples/flow_count_limit.rst
@@ -0,0 +1,7 @@
+Flow count limit
+----------------
+
+Limit the maximum number of active flows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: flow_count_limit.flow_count_limit
diff --git a/docs/examples/flow_gradient.rst b/docs/examples/flow_gradient.rst
@@ -0,0 +1,7 @@
+Flow gradient
+-------------
+
+Ramping of a power plant
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: gradient_example.gradient_example
diff --git a/docs/examples/index.rst b/docs/examples/index.rst
@@ -5,5 +5,28 @@ Examples
 
 .. toctree::
     :glob:
+    :maxdepth: 2
 
-    solph.examples*
+    basic_example.rst
+    time_index.rst
+    nametuple.rst
+    simple_dispatch.rst
+    cellular.rst
+    activity_costs.rst
+    min_max_runtimes.rst
+    startup_costs.rst
+    flow_gradient.rst
+    variable_chp.rst
+    unbalanced_storage.rst
+    storage_costs.rst
+    emission_constraint.rst
+    flow_count_limit.rst
+    storage_level_constraint.rst
+    electrical.transshipment.rst
+    excel_reader.rst
+    storage_investment.rst
+    shared_invest_limit.rst
+    minimal_investment.rst
+    invest_nonconvex.rst
+    electrical.lopf.rst
+    custom_constraints.rst
diff --git a/docs/examples/invest_nonconvex.rst b/docs/examples/invest_nonconvex.rst
@@ -0,0 +1,14 @@
+Combination of investment and binary status variable
+----------------------------------------------------
+
+Different components in common energy system
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. automodule:: invest_nonconvex_flow_examples.house_without_nonconvex_investment
+
+Same component but different Flows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. automodule:: invest_nonconvex_flow_examples.house_with_nonconvex_investment
+
+Same Flow
+~~~~~~~~~
+.. automodule:: invest_nonconvex_flow_examples.diesel_genset_nonconvex_investment
diff --git a/docs/examples/min_max_runtimes.rst b/docs/examples/min_max_runtimes.rst
@@ -0,0 +1,9 @@
+.. _runtime_limit_example_label:
+
+Minimal and maximal runtime
+---------------------------
+
+Constraining uptime and downtime of plants
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: min_max_runtimes.min_max_runtimes
diff --git a/docs/examples/minimal_investment.rst b/docs/examples/minimal_investment.rst
@@ -0,0 +1,7 @@
+Investment with minimal invest
+------------------------------
+
+Transformer with minimum size
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: investment_with_minimal_invest.minimal_invest
diff --git a/docs/examples/nametuple.rst b/docs/examples/nametuple.rst
@@ -0,0 +1,7 @@
+Tuple as label
+--------------
+
+Using tuples as names for components
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: tuple_as_labels.tuple_as_label
diff --git a/docs/examples/shared_invest_limit.rst b/docs/examples/shared_invest_limit.rst
@@ -0,0 +1,7 @@
+Generic Invest limit
+--------------------
+
+Concurrence for building space
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: generic_invest_limit.example_generic_invest
diff --git a/docs/examples/simple_dispatch.rst b/docs/examples/simple_dispatch.rst
@@ -0,0 +1,7 @@
+Simple heat and power dispatch
+------------------------------
+
+Linear dispatch optimization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: simple_dispatch.simple_dispatch