Add to documentation (Hackathon 4/10+11)

doc/conf.py

@@ -34,10 +34,10 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    #'sphinx.ext.autodoc',
+    "sphinx.ext.autodoc",
     #'sphinx.ext.autosummary',
     "myst_parser",
-    "sphinx.ext.autosectionlabel",
+    # "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
     "sphinx.ext.mathjax",
@@ -50,6 +50,19 @@
     "sphinx.ext.imgconverter",  # for SVG conversion
 ]
 
+autodoc_mock_imports = [
+    "atlite",
+    "snakemake",
+    "pycountry",
+    "rioxarray",
+    "country_converter",
+    "tabula",
+    "memory_profiler",
+    "powerplantmatching",
+    "rasterio",
+    "dask.distributed",
+]
+
 autodoc_default_flags = ["members"]
 autosummary_generate = True
 

doc/configuration.rst

@@ -90,9 +90,9 @@ For each wildcard, a **list of values** is provided. The rule
 ``results/networks/elec_s{simpl}_{clusters}_ec_l{ll}_{opts}.nc`` for **all
 combinations** of the provided wildcard values as defined by Python's
 `itertools.product(...)
-<https://docs.python.org/2/library/itertools.html#itertools.product>`_ function
+<https://docs.python.org/2/library/itertools.html#itertools.product>`__ function
 that snakemake's `expand(...) function
-<https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#targets>`_
+<https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#targets>`__
 uses.
 
 An exemplary dependency graph (starting from the simplification rules) then looks like this:
@@ -129,7 +129,7 @@ An exemplary dependency graph (starting from the simplification rules) then look
 ``snapshots``
 =============
 
-Specifies the temporal range to build an energy system model for as arguments to `pandas.date_range <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.date_range.html>`_
+Specifies the temporal range to build an energy system model for as arguments to `pandas.date_range <https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.date_range.html>`__
 
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
@@ -197,7 +197,7 @@ Switches for some rules and optional features.
 ``atlite``
 ==========
 
-Define and specify the ``atlite.Cutout`` used for calculating renewable potentials and time-series. All options except for ``features`` are directly used as `cutout parameters <https://atlite.readthedocs.io/en/latest/ref_api.html#cutout>`_.
+Define and specify the ``atlite.Cutout`` used for calculating renewable potentials and time-series. All options except for ``features`` are directly used as `cutout parameters <https://atlite.readthedocs.io/en/latest/ref_api.html#cutout>`__.
 
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml
@@ -427,7 +427,7 @@ overwrite the existing values.
    :widths: 22,7,22,33
    :file: configtables/biomass.csv
 
-The list of available biomass is given by the category in `ENSPRESO_BIOMASS <https://cidportal.jrc.ec.europa.eu/ftp/jrc-opendata/ENSPRESO/ENSPRESO_BIOMASS.xlsx>`_, namely:
+The list of available biomass is given by the category in `ENSPRESO_BIOMASS <https://cidportal.jrc.ec.europa.eu/ftp/jrc-opendata/ENSPRESO/ENSPRESO_BIOMASS.xlsx>`__, namely:
 
 - Agricultural waste
 - Manure solid, liquid
@@ -564,7 +564,7 @@ The list of available biomass is given by the category in `ENSPRESO_BIOMASS <htt
 .. _adjustments_cf:
 
 ``adjustments``
-=============
+===============
 
 .. literalinclude:: ../config/config.default.yaml
    :language: yaml

doc/contributing.rst

@@ -35,3 +35,15 @@ including our own are reviewed by a second person before they are incorporated i
 If you are unfamiliar with pull requests, the GitHub help pages have a nice `guide <https://help.github.com/en/articles/about-pull-requests>`_.
 
 To ask and answer general usage questions, join the `PyPSA mailing list <https://groups.google.com/forum/#!forum/pypsa>`_.
+
+Contributing to the documentation
+====================================
+
+We strive to keep documentation useful and up to date for all PyPSA users. If you encounter an area where documentation is not available or insufficient, we very much welcome your contribution. Here is How To:
+
+#. Install the conda environment for documentation from the `PyPSA repository <https://github.com/PyPSA/PyPSA/blob/master/environment_docs.yml>`_.
+   (Here is `how to install a conda environment <https://pypsa-eur.readthedocs.io/en/latest/installation.html#install-python-dependencies>`_.)
+#. Make your changes in the corresponding .rst file under ``pypsa-eur/doc``.
+#. Compile your changes by running the following command in your terminal in the ``doc`` folder: ``make html``
+   You may encounter some warnings, but end up with a message such as ``build succeeded, XX warnings.``. html files to review your changes can then be found under ``doc/_build/html``.
+#. Contribute your documentation in a pull request (`here is a guide <https://help.github.com/en/articles/about-pull-requests>`_).

doc/costs.rst

@@ -8,7 +8,7 @@ Techno-Economic Assumptions
 ############################
 
 The database of cost assumptions is retrieved from the repository
-`PyPSA/technology-data <https://github.com/pypsa/technology-data>`_ and then
+`PyPSA/technology-data <https://github.com/pypsa/technology-data>`__ and then
 saved to a file ``resources/costs_{year}.csv``. The ``config/config.yaml`` provides options
 to choose a reference year and use a specific version of the repository.
 
@@ -30,7 +30,7 @@ years compiled from various sources, namely for
 - carbon-dioxide intensity.
 
 Many values are taken from a database published by the Danish Energy Agency (`DEA
-<https://ens.dk/en/our-services/projections-and-models/technology-data>`_).
+<https://ens.dk/en/our-services/projections-and-models/technology-data>`__).
 
 
 The given overnight capital costs are annualised to net present costs

doc/foresight.rst

@@ -166,13 +166,13 @@ Options
 
 The total carbon budget for the entire transition path can be indicated in the
 `sector_opts
-<https://github.com/PyPSA/pypsa-eur-sec/blob/f13902510010b734c510c38c4cae99356f683058/config.default.yaml#L25>`_
+<https://github.com/PyPSA/pypsa-eur-sec/blob/f13902510010b734c510c38c4cae99356f683058/config.default.yaml#L25>`__
 in ``config/config.yaml``. The carbon budget can be split among the
 ``planning_horizons`` following an exponential or beta decay. E.g. ``'cb40ex0'``
 splits a carbon budget equal to 40 Gt :math:`_{CO_2}` following an exponential
 decay whose initial linear growth rate r is zero. They can also follow some
 user-specified path, if defined `here
-<https://github.com/PyPSA/pypsa-eur-sec/blob/413254e241fb37f55b41caba7264644805ad8e97/config.default.yaml#L56>`_.
+<https://github.com/PyPSA/pypsa-eur-sec/blob/413254e241fb37f55b41caba7264644805ad8e97/config.default.yaml#L56>`__.
 The paper `Speed of technological transformations required in Europe to achieve
 different climate goals (2022) <https://doi.org/10.1016/j.joule.2022.04.016>`__
 defines CO_2 budgets corresponding to global temperature increases (1.5C – 2C)

doc/index.rst

@@ -81,16 +81,16 @@ them:
 .. note::
     You can find showcases of the model's capabilities in the Supplementary Materials of the
     Joule paper `The potential role of a hydrogen network in Europe
-    <https://doi.org/10.1016/j.joule.2023.06.016>`_, the Supplementary Materials of another `paper in Joule with a
+    <https://doi.org/10.1016/j.joule.2023.06.016>`__, the Supplementary Materials of another `paper in Joule with a
     description of the industry sector
-    <https://doi.org/10.1016/j.joule.2022.04.016>`_, or in `a 2021 presentation
-    at EMP-E <https://nworbmot.org/energy/brown-empe.pdf>`_.
+    <https://doi.org/10.1016/j.joule.2022.04.016>`__, or in `a 2021 presentation
+    at EMP-E <https://nworbmot.org/energy/brown-empe.pdf>`__.
     The sector-coupled extension of PyPSA-Eur was
     initially described in the paper `Synergies of sector coupling and transmission
     reinforcement in a cost-optimised, highly renewable European energy system
-    <https://arxiv.org/abs/1801.05290>`_ (2018) but it differs by being based on the
+    <https://arxiv.org/abs/1801.05290>`__ (2018) but it differs by being based on the
     higher resolution electricity transmission model `PyPSA-Eur
-    <https://github.com/PyPSA/pypsa-eur>`_ rather than a one-node-per-country model,
+    <https://github.com/PyPSA/pypsa-eur>`__ rather than a one-node-per-country model,
     and by including biomass, industry, industrial feedstocks, aviation, shipping,
     better carbon management, carbon capture and usage/sequestration, and gas
     networks.
@@ -99,8 +99,8 @@ About
 =====
 
 PyPSA-Eur is designed to be imported into the open energy system modelling
-framework `PyPSA <https://www.pypsa.org>`_ for which `documentation
-<https://pypsa.readthedocs.io>`_ is available as well. However, since the
+framework `PyPSA <https://www.pypsa.org>`__ for which `documentation
+<https://pypsa.readthedocs.io>`__ is available as well. However, since the
 workflow is modular, it should be easy to adapt the data workflow to other
 modelling frameworks.
 
@@ -114,22 +114,22 @@ of the individual parts.
     PyPSA-Eur is under active development and has several
     :doc:`limitations` which
     you should understand before using the model. The Github repository
-    `issues <https://github.com/PyPSA/pypsa-eur/issues>`_ collect known
+    `issues <https://github.com/PyPSA/pypsa-eur/issues>`__ collect known
     topics we are working on. Please feel free to help or make suggestions.
 
 This project is currently maintained by the `Department of Digital
-Transformation in Energy Systems <https://www.tu.berlin/en/ensys>`_ at the
-`Technische Universität Berlin <https://www.tu.berlin>`_. Previous versions were
-developed within the `IAI <http://www.iai.kit.edu>`_ at the `Karlsruhe Institute
-of Technology (KIT) <http://www.kit.edu/english/index.php>`_ which was funded by
-the `Helmholtz Association <https://www.helmholtz.de/en/>`_, and by the
+Transformation in Energy Systems <https://www.tu.berlin/en/ensys>`__ at the
+`Technische Universität Berlin <https://www.tu.berlin>`__. Previous versions were
+developed within the `IAI <http://www.iai.kit.edu>`__ at the `Karlsruhe Institute
+of Technology (KIT) <http://www.kit.edu/english/index.php>`__ which was funded by
+the `Helmholtz Association <https://www.helmholtz.de/en/>`__, and by the
 `Renewable Energy Group
-<https://fias.uni-frankfurt.de/physics/schramm/renewable-energy-system-and-network-analysis/>`_
-at `FIAS <https://fias.uni-frankfurt.de/>`_ to carry out simulations for the
-`CoNDyNet project <http://condynet.de/>`_, financed by the `German Federal
-Ministry for Education and Research (BMBF) <https://www.bmbf.de/en/index.html>`_
+<https://fias.uni-frankfurt.de/physics/schramm/renewable-energy-system-and-network-analysis/>`__
+at `FIAS <https://fias.uni-frankfurt.de/>`__ to carry out simulations for the
+`CoNDyNet project <http://condynet.de/>`__, financed by the `German Federal
+Ministry for Education and Research (BMBF) <https://www.bmbf.de/en/index.html>`__
 as part of the `Stromnetze Research Initiative
-<http://forschung-stromnetze.info/projekte/grundlagen-und-konzepte-fuer-effiziente-dezentrale-stromnetze/>`_.
+<http://forschung-stromnetze.info/projekte/grundlagen-und-konzepte-fuer-effiziente-dezentrale-stromnetze/>`__.
 
 
 Workflow
@@ -153,10 +153,10 @@ to reading this documentation.
 
 - Documentation of `PyPSA <https://pypsa.readthedocs.io>`__, the package for
   modelling energy systems which PyPSA-Eur uses under the hood.
-- Course on `Energy Systems <https://nworbmot.org/courses/es-22/>`_ given at
-  Technical University of Berlin by `Prof. Dr. Tom Brown <https://nworbmot.org>`_.
-- Course on `Data Science for Energy System Modelling <https://fneum.github.io/data-science-for-esm/intro.html>`_
-  given at Technical University of Berlin by `Dr. Fabian Neumann <https://neumann.fyi>`_.
+- Course on `Energy Systems <https://nworbmot.org/courses/es-22/>`__ given at
+  Technical University of Berlin by `Prof. Dr. Tom Brown <https://nworbmot.org>`__.
+- Course on `Data Science for Energy System Modelling <https://fneum.github.io/data-science-for-esm/intro.html>`__
+  given at Technical University of Berlin by `Dr. Fabian Neumann <https://neumann.fyi>`__.
 
 
 Citing PyPSA-Eur

doc/installation.rst

@@ -15,7 +15,7 @@ directory in which the commands following the ``%`` should be entered.
 Clone the Repository
 ====================
 
-First of all, clone the `PyPSA-Eur repository <https://github.com/PyPSA/pypsa-eur>`_ using the version control system ``git`` in the command line.
+First of all, clone the `PyPSA-Eur repository <https://github.com/PyPSA/pypsa-eur>`__ using the version control system ``git`` in the command line.
 
 .. code:: bash
 
@@ -30,11 +30,11 @@ Install Python Dependencies
 ===============================
 
 PyPSA-Eur relies on a set of other Python packages to function.
-We recommend using the package manager `mamba <https://mamba.readthedocs.io/en/latest/>`_ to install them and manage your environments.
-For instructions for your operating system follow the ``mamba`` `installation guide <https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html>`_.
+We recommend using the package manager `mamba <https://mamba.readthedocs.io/en/latest/>`__ to install them and manage your environments.
+For instructions for your operating system follow the ``mamba`` `installation guide <https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html>`__.
 You can also use ``conda`` equivalently.
 
-The package requirements are curated in the `envs/environment.yaml <https://github.com/PyPSA/pypsa-eur/blob/master/envs/environment.yaml>`_ file.
+The package requirements are curated in the `envs/environment.yaml <https://github.com/PyPSA/pypsa-eur/blob/master/envs/environment.yaml>`__ file.
 The environment can be installed and activated using
 
 .. code:: bash
@@ -59,24 +59,24 @@ Install a Solver
 PyPSA passes the PyPSA-Eur network model to an external solver for performing the optimisation.
 PyPSA is known to work with the free software
 
-- `HiGHS <https://highs.dev/>`_
-- `Cbc <https://projects.coin-or.org/Cbc#DownloadandInstall>`_
-- `GLPK <https://www.gnu.org/software/glpk/>`_ (`WinGLKP <http://winglpk.sourceforge.net/>`_)
-- `Ipopt <https://coin-or.github.io/Ipopt/INSTALL.html>`_
+- `HiGHS <https://highs.dev/>`__
+- `Cbc <https://projects.coin-or.org/Cbc#DownloadandInstall>`__
+- `GLPK <https://www.gnu.org/software/glpk/>`__ (`WinGLKP <http://winglpk.sourceforge.net/>`__)
+- `Ipopt <https://coin-or.github.io/Ipopt/INSTALL.html>`__
 
 and the non-free, commercial software (for some of which free academic licenses are available)
 
-- `Gurobi <https://www.gurobi.com/documentation/quickstart.html>`_
-- `CPLEX <https://www.ibm.com/products/ilog-cplex-optimization-studio>`_
-- `FICO Xpress Solver <https://www.fico.com/de/products/fico-xpress-solver>`_
+- `Gurobi <https://www.gurobi.com/documentation/quickstart.html>`__
+- `CPLEX <https://www.ibm.com/products/ilog-cplex-optimization-studio>`__
+- `FICO Xpress Solver <https://www.fico.com/de/products/fico-xpress-solver>`__
 
 For installation instructions of these solvers for your operating system, follow the links above.
 Commercial solvers such as Gurobi and CPLEX currently significantly outperform open-source solvers for large-scale problems, and
 it might be the case that you can only retrieve solutions by using a commercial solver.
 Nevertheless, you can still use open-source solvers for smaller problems.
 
 .. seealso::
-    `Instructions how to install a solver in the documentation of PyPSA <https://pypsa.readthedocs.io/en/latest/installation.html#getting-a-solver-for-linear-optimisation>`_
+    `Instructions how to install a solver in the documentation of PyPSA <https://pypsa.readthedocs.io/en/latest/installation.html#getting-a-solver-for-linear-optimisation>`__
 
 .. note::
     The rules :mod:`cluster_network` and :mod:`simplify_network` solve a mixed-integer quadratic optimisation problem for clustering.
@@ -88,7 +88,7 @@ Nevertheless, you can still use open-source solvers for smaller problems.
         mamba activate pypsa-eur
         mamba install -c gurobi gurobi
 
-    Additionally, you need to setup your `Gurobi license <https://www.gurobi.com/solutions/licensing/>`_.
+    Additionally, you need to setup your `Gurobi license <https://www.gurobi.com/solutions/licensing/>`__.
 
 
 .. _defaultconfig:

doc/introduction.rst

@@ -14,7 +14,7 @@
     <iframe width="832" height="468" src="https://www.youtube.com/embed/ty47YU1_eeQ" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 
 .. note::
-    Find the introductory slides `here <https://docs.google.com/presentation/d/e/2PACX-1vQGQZD7KIVdocRZzRVu8Uk-JC_ltEow5zjtIarhyws46IMJpaqGuux695yincmJA_i5bVEibEs7z2eo/pub?start=false&loop=true&delayms=3000>`_.
+    Find the introductory slides `here <https://docs.google.com/presentation/d/e/2PACX-1vQGQZD7KIVdocRZzRVu8Uk-JC_ltEow5zjtIarhyws46IMJpaqGuux695yincmJA_i5bVEibEs7z2eo/pub?start=false&loop=true&delayms=3000>`__.
 
 .. warning::
     The video only introduces the electricity-only part of PyPSA-Eur.
@@ -23,7 +23,7 @@ Workflow
 =========
 
 The generation of the model is controlled by the open workflow management system
-`Snakemake <https://snakemake.github.io/>`_. In a nutshell, the ``Snakefile``
+`Snakemake <https://snakemake.github.io/>`__. In a nutshell, the ``Snakefile``
 declares for each script in the ``scripts`` directory a rule which describes
 which files the scripts consume and produce (their corresponding input and
 output files). The ``snakemake`` tool then runs the scripts in the correct order
@@ -54,20 +54,20 @@ preceding rules which another rule takes as input data.
 
 For the use of ``snakemake``, it makes sense to familiarize yourself quickly
 with the `basic tutorial
-<https://snakemake.readthedocs.io/en/stable/tutorial/basics.html>`_ and then
+<https://snakemake.readthedocs.io/en/stable/tutorial/basics.html>`__ and then
 read carefully through the documentation of the `command line interface
-<https://snakemake.readthedocs.io/en/stable/executing/cli.html>`_, noting the
+<https://snakemake.readthedocs.io/en/stable/executing/cli.html>`__, noting the
 arguments ``-j``, ``-c``, ``-f``, ``-F``, ``-n``, ``-r``, ``--dag`` and ``-t``
 in particular.
 
 Scenarios, Configuration and Modification
 =========================================
 
 It is easy to run PyPSA-Eur for multiple scenarios using the `wildcards feature
-<https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#wildcards>`_
+<https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#wildcards>`__
 of ``snakemake``. Wildcards allow to generalise a rule to produce all files that
 follow a `regular expression
-<https://en.wikipedia.org/wiki/Regular_expression>`_ pattern, which defines
+<https://en.wikipedia.org/wiki/Regular_expression>`__ pattern, which defines
 a particular scenario. One can think of a wildcard as a parameter that shows
 up in the input/output file names and thereby determines which rules to run,
 what data to retrieve and what files to produce. Details are explained in
@@ -97,5 +97,5 @@ System Requirements
 
 Building the model with the scripts in this repository runs on a regular computer.
 But optimising for investment and operation decisions across many scenarios requires a strong interior-point solver
-like `Gurobi <http://www.gurobi.com/>`_ or `CPLEX <https://www.ibm.com/analytics/cplex-optimizer>`_ with more memory.
+like `Gurobi <http://www.gurobi.com/>`__ or `CPLEX <https://www.ibm.com/analytics/cplex-optimizer>`__ with more memory.
 Open-source solvers like `HiGHS <https://highs.dev>` can also be used for smaller problems.