Merge pull request #1007 from pz-max/readme1

add readme and intro fix

README.md

@@ -39,6 +39,8 @@ The model is described in the Applied Energy article "PyPSA-Earth. A new global
   <img src="https://forum.openmod.org/uploads/db8804/original/1X/6af089c376b19b72ad148e4e4326c162b94db68f.png" width=35%>
 </p>
 
+<p align="center"><b> Figure:</b> Example power systems build with PyPSA-Earth. See images of ~193 more countries at <a>https://zenodo.org/records/10080766</a></p>
+
 ## Livetracker. Most popular global models:
 
 <p align="center">

doc/how_to_contribute.rst

@@ -60,6 +60,48 @@ like `snakeviz <https://jiffyclub.github.io/snakeviz/>`_. See a detailed example
 in `this discussion #557 <https://github.com/pypsa-meets-earth/pypsa-earth/discussions/557>`_.
 
 
+Documentation
+-------------
+
+To create the documentation locally, you need `Sphinx <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ . It can be installed using specifications
+from `doc/requirements.txt`. First, we recommend creating a fresh conda environment and activate it:
+
+.. code:: bash
+
+    .../pypsa-earth % conda create --name pypsa-earth-docs python
+
+    .../pypsa-earth % conda activate pypsa-earth-docs
+
+Next, install the packages specified in `doc/requirements.txt` using `pip`:
+
+.. code:: bash
+
+    .../pypsa-earth % pip install -r doc/requirements.txt
+
+
+Once installation is completed, the following commands allow you to create the documentation locally:
+
+.. code:: bash
+
+    .../pypsa-earth (pypsa-earth-docs) % cd doc
+
+    .../pypsa-earth/doc (pypsa-earth-docs) % make html
+
+This will create html files in `pypsa-earth/doc/_build/html`.
+VScode provides a so called Liveserver extension such that the html file can be opened locally on your computer.
+
+.. warning::
+
+    Windows users might face some challenges when building the documentation locally using `make`. A workaround can be found, but might be time consuming. For instance:
+
+    1. If using Windows PowerShell, one might need to replace the command `make html` above by `./make html`. For more details on what is going on, see `this post <https://stackoverflow.com/questions/65471557/make-html-not-working-for-sphinx-documentation-in-windows-10>`_ on Stack Overflow.
+
+.. note::
+
+    The documentation is built automatically by the CI for every pull request. The documentation is hosted on `ReadTheDocs <https://pypsa-earth.readthedocs.io/en/latest/>`_.
+    For more information on our documentation infrastructure and syntax tips, see `this page <https://pypsa-earth.readthedocs.io/en/latest/how_to_docs.html>`_.
+
+
 No-Code
 ========
 Instead of contributing code there are alternatives to support the PyPSA-Earth goals.

doc/how_to_docs.rst

@@ -35,39 +35,3 @@ We found three important files/file groups for the documentation:
 The images for documentation should be placed into `documentation <https://github.com/pypsa-meets-earth/documentation>`_ repository to the folder "doc/img". The content of the folder "documentation/doc/img/" is copied into "pypsa-earth/doc/img/" during building PyPSA-Earth documentation.
 
 Please, if you have problems with the documentation create an issue and let us know
-
-Compile the documentation locally
-----------------------------------
-
-To create the documentation locally, you need `Sphinx <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ . It can be installed using specifications
-form `doc/requirements.txt`. First, we recommend creating a fresh python environment and activate it:
-
-.. code:: bash
-
-    .../pypsa-earth % conda create --name pypsa-earth-docs python
-
-    .../pypsa-earth % conda activate pypsa-earth-docs
-
-Next, install the packages specified in `doc/requirements.txt` using `pip`:
-
-.. code:: bash
-
-    .../pypsa-earth % pip install -r doc/requirements.txt
-
-
-Once installation is completed, the following commands allow you to create the documentation locally:
-
-.. code:: bash
-
-    .../pypsa-earth (pypsa-earth-docs) % cd doc
-
-    .../pypsa-earth/doc (pypsa-earth-docs) % make html
-
-This will create html files in `pypsa-earth/doc/_build/html`.
-VScode provides a so called Liveserver extension such that the html file can be opened locally on your computer.
-
-.. note::
-
-    Windows users might face some challenges when building the documentation locally using `make`. A workaround can be found, but might be time consuming. For instance:
-
-    1. If using Windows PowerShell, one might need to replace the command `make html` above by `./make html`. For more details on what is going on, see `this post <https://stackoverflow.com/questions/65471557/make-html-not-working-for-sphinx-documentation-in-windows-10>`_ on Stack Overflow.

doc/index.rst

@@ -71,9 +71,16 @@ myopic and perfect pathway expansion capabilities.
 *PyPSA meets Earth initiative* members are maintaining the *PyPSA-Earth* repository as well as many other tools.
 The `website <https://pypsa-meets-earth.github.io/>`_ provides more context of the initiative and the associated projects.
 
-.. image:: img/africa_osm_map.png
-    :width: 60%
-    :align: center
+.. list-table::
+   :width: 100%
+   :class: borderless
+
+   * - .. image:: https://forum.openmod.org/uploads/db8804/original/1X/ddf041d1b98ca8f8c310f1c6393ec426ab5594cf.png
+     - .. image:: https://forum.openmod.org/uploads/db8804/original/1X/940b2673cfc31c4a6f01b7908f546d39d67df27e.png
+     - .. image:: https://forum.openmod.org/uploads/db8804/original/1X/6af089c376b19b72ad148e4e4326c162b94db68f.png
+
+**Figure:** Example power systems build with PyPSA-Earth. See images of ~193 more countries at https://zenodo.org/records/10080766
+
 
 ==============
 Get Involved

doc/introduction.rst

@@ -14,16 +14,16 @@ A short video explaining the logic of PyPSA-Eur which is similar to PyPSA-Earth:
 
     <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>
 
-For more details on PyPSA-Earth read our milestone paper: Parzen et al., "PyPSA-Earth. A New Global Open Energy System Optimization Model Demonstrated in Africa", 2022, https://arxiv.org/abs/2209.04663.
-Please use the following BibTeX: ::
+For more details on PyPSA-Earth read the below milestone paper.
+For citations, please use the following BibTeX: ::
 
   @misc{PyPSAEarth,
   author = {Parzen, Maximilian and Abdel-Khalek, Hazem and Fedorova, Ekaterina and Mahmood, Matin and Frysztacki, Martha Maria and Hampp, Johannes and Franken, Lukas and Schumm, Leon and Neumann, Fabian and Poli, Davide and Kiprakis, Aristides and Fioriti, Davide},
-  title = {PyPSA-Earth. A New Global Open Energy System Optimization Model Demonstrated in Africa},
-  publisher = {arXiv},
-  year = {2022},
-  url = {https://arxiv.org/abs/2209.04663},
-  doi = {10.48550/ARXIV.2209.04663},
+  title = {PyPSA-Earth. A new global open energy system optimization model demonstrated in Africa},
+  publisher = {Applied Energy},
+  year = {2023},
+  url = {https://www.sciencedirect.com/science/article/pii/S030626192300460},
+  doi = {https://doi.org/10.1016/j.apenergy.2023.121096},
   }
 
 

doc/release_notes.rst

@@ -34,6 +34,8 @@ E.g. if a new rule becomes available describe how to use it `snakemake -j1 run_t
 
 * Revise bus region definition by gadm. `PR #1001 <https://github.com/pypsa-meets-earth/pypsa-earth/pull/1001>`__
 
+* Documentation improvements. `PR ##1007 <https://github.com/pypsa-meets-earth/pypsa-earth/pull/1007>`__
+
 PyPSA-Earth 0.3.0
 =================