diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 24eb15064..f4767dc96 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -8,7 +8,7 @@ - [ ] I consent to the release of this PR's code under the GPLv3 license and non-code contributions under CC0-1.0 and CC-BY-4.0. - [ ] I tested my contribution locally and it seems to work fine. - [ ] Code and workflow changes are sufficiently documented. -- [ ] Newly introduced dependencies are added to `envs/environment.yaml` and `envs/environment.docs.yaml`. +- [ ] Newly introduced dependencies are added to `envs/environment.yaml` and `doc/requirements.txt`. - [ ] Changes in configuration options are added in all of `config.default.yaml` and `config.tutorial.yaml`. - [ ] Add a test config or line additions to `test/` (note tests are changing the config.tutorial.yaml) - [ ] Changes in configuration options are also documented in `doc/configtables/*.csv` and line references are adjusted in `doc/configuration.rst` and `doc/tutorial.rst`. diff --git a/doc/how_to_docs.rst b/doc/how_to_docs.rst index 1fe1833ee..462b04511 100644 --- a/doc/how_to_docs.rst +++ b/doc/how_to_docs.rst @@ -39,16 +39,23 @@ Please, if you have problems with the documentation create an issue and let us k Compile the documentation locally ---------------------------------- -To create the documentation locally, you need sphinx. It may be installed using specification -form `doc/environment.docs.yaml` like is was done when creating `pypsa-earth` environment: +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 % mamba env create -f envs/environment.docs.yaml + .../pypsa-earth % conda create --name pypsa-earth-docs python - .../pypsa-earth % conda activate pypsa-earth-docs + .../pypsa-earth % conda activate pypsa-earth-docs -Then the following commands allow you to create the documentation locally: +Next, install the packages specified in `doc/requiremnts.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 @@ -58,3 +65,9 @@ Then the following commands allow you to create the documentation locally: 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/release_notes.rst b/doc/release_notes.rst index 8ee361ba1..a1c430d3f 100644 --- a/doc/release_notes.rst +++ b/doc/release_notes.rst @@ -106,7 +106,9 @@ PyPSA-Earth 0.2.0 * Improve earth coverage and add improve make_statistics coverage `PR #654 `__ -* Fix bug for missing renewable profiles and generators `PR #714 https://github.com/pypsa-meets-earth/pypsa-earth/pull/714`__ +* Fix bug for missing renewable profiles and generators `PR #714 `__ + +* Update instructions on how to write documentation. `PR #720 `__ PyPSA-Earth 0.1.0 ================= diff --git a/envs/environment.docs.yaml b/envs/environment.docs.yaml deleted file mode 100644 index 8a3c3b8c4..000000000 --- a/envs/environment.docs.yaml +++ /dev/null @@ -1,74 +0,0 @@ -# SPDX-FileCopyrightText: PyPSA-Earth and PyPSA-Eur Authors -# -# SPDX-License-Identifier: GPL-3.0-or-later - -name: pypsa-earth-docs -channels: -- conda-forge/label/shapely_dev -- conda-forge -- bioconda -- http://conda.anaconda.org/gurobi -dependencies: -- python>=3.8 -- pip -- mamba # esp for windows build - -- pypsa>=0.17.1 -- atlite>=0.2.4 -- dask<=2021.3.1 # until https://github.com/dask/dask/issues/7583 is solved -- earth-osm==0.0.8 # until 0.1.0 - - # Dependencies of the workflow itself -- xlrd -- openpyxl -- pycountry -- seaborn -- snakemake-minimal -- memory_profiler -- ruamel.yaml -- yaml -- pytables -- lxml -- powerplantmatching>=0.4.8 -- numpy -- pandas -- geopandas -- xarray -- netcdf4 -- networkx -- scipy -- pydoe2 -- shapely>=1.8a1 -- progressbar2 -- pyomo -- matplotlib - - # Keep in conda environment when calling ipython -- ipython - - # GIS dependencies: -- cartopy -- descartes -- rasterio -- geoviews -- hvplot -- rioxarray - - # PyPSA-Eur-Sec Dependencies -- geopy -- tqdm -- pytz -- reverse-geocode -- country_converter - -- pip: - - git+https://github.com/pydata/xarray@main # till the main is not in conda - - git+https://github.com/pypsa/pypsa.git#egg=pypsa - - vresutils==0.3.1 - - tsam>=1.1.0 - - chaospy # lastest version only available on pip - - sphinx - - sphinx_rtd_theme - - nbsphinx - - nbsphinx_link - - gitpython