diff --git a/README.md b/README.md index 7a7a76767..62542af76 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,8 @@ The model is described in the Applied Energy article "PyPSA-Earth. A new global

+

Figure: Example power systems build with PyPSA-Earth. See images of ~193 more countries at https://zenodo.org/records/10080766

+ ## Livetracker. Most popular global models:

diff --git a/doc/how_to_contribute.rst b/doc/how_to_contribute.rst index 1553ffc76..8fffc1123 100644 --- a/doc/how_to_contribute.rst +++ b/doc/how_to_contribute.rst @@ -60,6 +60,48 @@ like `snakeviz `_. See a detailed example in `this discussion #557 `_. +Documentation +------------- + +To create the documentation locally, you need `Sphinx `_ . 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 `_ on Stack Overflow. + +.. note:: + + The documentation is built automatically by the CI for every pull request. The documentation is hosted on `ReadTheDocs `_. + For more information on our documentation infrastructure and syntax tips, see `this page `_. + + No-Code ======== Instead of contributing code there are alternatives to support the PyPSA-Earth goals. diff --git a/doc/how_to_docs.rst b/doc/how_to_docs.rst index c1d10c8c3..85ea9ff31 100644 --- a/doc/how_to_docs.rst +++ b/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 `_ 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 `_ . 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 `_ on Stack Overflow. diff --git a/doc/index.rst b/doc/index.rst index 3a7cf7b38..0f7e5c20c 100644 --- a/doc/index.rst +++ b/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 `_ 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 diff --git a/doc/introduction.rst b/doc/introduction.rst index 7b6eb91e1..f4c9394c7 100644 --- a/doc/introduction.rst +++ b/doc/introduction.rst @@ -14,16 +14,16 @@ A short video explaining the logic of PyPSA-Eur which is similar to PyPSA-Earth: -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}, } diff --git a/doc/release_notes.rst b/doc/release_notes.rst index ba5ea8d8c..b8c16bb08 100644 --- a/doc/release_notes.rst +++ b/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 `__ +* Documentation improvements. `PR ##1007 `__ + PyPSA-Earth 0.3.0 =================